From: Chris Nandor Date: Mon, 3 Aug 1998 13:35:25 +0000 (-0400) Subject: perlport 1.30 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=b8099c3db5f7e0467eefe57795cb4028f9ecb7a6;p=p5sagit%2Fp5-mst-13.2.git perlport 1.30 Message-Id: p4raw-id: //depot/maint-5.005/perl@1724 --- diff --git a/pod/perlport.pod b/pod/perlport.pod index d4c4db8..ac40b57 100644 --- a/pod/perlport.pod +++ b/pod/perlport.pod @@ -65,7 +65,7 @@ important thing is to decide where the code will run, and to be deliberate in your decision. This information should not be considered complete; it includes possibly -transient information about idiosyncracies of some of the ports, almost +transient information about idiosyncrasies of some of the ports, almost all of which are in a state of constant evolution. Thus this material should be considered a perpetual work in progress (EIMG SRC="yellow_sign.gif" ALT="Under Construction"E). @@ -148,11 +148,13 @@ notion of a "path" to uniquely identify a file on the system. Just how that path is actually written, differs. While they are similar, file path specifications differ between Unix, -Windows, S, OS/2, VMS and probably others. Unix, for example, is -one of the few OSes that has the idea of a root directory. S -uses C<:> as a path separator instead of C. VMS, Windows, and OS/2 -can work similarly to Unix with C as path separator, or in their own -idiosyncratic ways. +Windows, S, OS/2, VMS, S and probably others. Unix, +for example, is one of the few OSes that has the idea of a root directory. +S uses C<:> as a path separator instead of C. VMS, Windows, and +OS/2 can work similarly to Unix with C as path separator, or in their own +idiosyncratic ways. C perl can emulate Unix filenames with C +as path separator, or go native and use C<.> for path separator and C<:> +to signal filing systems and disc names. As with the newline problem above, there are modules that can help. The C modules provide methods to do the Right Thing on whatever @@ -185,6 +187,10 @@ F. If code does need to rely on such a file, include a description of the file and its format in the code's documentation, and make it easy for the user to override the default location of the file. +Don't assume that a you can open a full pathname for input with +C, as some platforms can use characters such as C> +which will perl C will interpret and eat. + =head2 System Interaction @@ -208,6 +214,9 @@ Don't count on signals in portable programs. Don't count on filename globbing. Use C, C, and C instead. +Don't count on per-program environment variables, or per-program current +directores. + =head2 Interprocess Communication (IPC) @@ -402,7 +411,7 @@ from calling any external programs, C will work just fine, and probably better, as it is more consistent with popular usage, and avoids the problem of remembering what to backwhack and what not to. -The DOS FAT file system can only accomodate "8.3" style filenames. Under +The DOS FAT file system can only accommodate "8.3" style filenames. Under the "case insensitive, but case preserving" HPFS (OS/2) and NTFS (NT) file systems you may have to be careful about case returned with functions like C or used with functions like C or C. @@ -566,7 +575,7 @@ extensions is also 39 characters. Version is a number from 1 to VMS' RMS filesystem is case insensitive and does not preserve case. C returns lowercased filenames, but specifying a file for -opening remains case insensitive. Files without extensions have a +opening remains case insensitive. Files without extensions have a trailing period on them, so doing a C with a file named F will return F (though that file could be opened with C. @@ -679,16 +688,138 @@ general usage issues for all EBCDIC Perls. Send a message body of =back + +=head2 Acorn RISC OS + +As Acorns use ASCII with newlines (C<\n>) in text files as C<\012> like Unix +and Unix filename emulation is turned on by default, it is quite likely that +most simple scripts will work "out of the box". The native filing system is +modular, and individual filing systems are free to be case sensitive or +insensitive, usually case preserving. Some native filing systems have name +length limits which file and directory names are silently truncated to fit - +scripts should be aware that the standard disc filing system currently has +a name length limit of B<10> characters, with up to 77 items in a directory, +but other filing systems may not impose such limitations. + +Native filenames are of the form + + Filesystem#Special_Field::DiscName.$.Directory.Directory.File + +where + + Special_Field is not usually present, but may contain . and $ . + Filesystem =~ m|[A-Za-z0-9_]| + DsicName =~ m|[A-Za-z0-9_/]| + $ represents the root directory + . is the path separator + @ is the current directory (per filesystem but machine global) + ^ is the parent directory + Directory and File =~ m|[^\0- "\.\$\%\&:\@\\^\|\177]+| + +The default filename translation is roughly C + +Note that C<"ADFS::HardDisc.$.File" ne 'ADFS::HardDisc.$.File'> and that +the second stage of $ interpolation in regular expressions will fall foul +of the C<$.> if scripts are not careful. + +Logical paths specified by system variables containing comma separated +search lists are also allowed, hence C is a valid filename, +and the filesystem will prefix C with each section of C +until a name is made that points to an object on disc. Writing to a new +file C would only be allowed if C contains a +single item list. The filesystem will also expand system variables in +filenames if enclosed in angle brackets, so CSystem$DirE.Modules> +would look for the file S>. The obvious +implication of this is that BE>> +and should be protected when C is used for input. + +Because C<.> was in use as a directory separator and filenames could not +be assumed to be unique after 10 characters, Acorn implemented the C +compiler to strip the trailing C<.c> C<.h> C<.s> and C<.o> suffix from +filenames specified in source code and store the respective files in +subdirectories named after the suffix. Hence files are translated: + + foo.h h.foo + C:foo.h C:h.foo (logical path variable) + sys/os.h sys.h.os (C compiler groks Unix-speak) + 10charname.c c.10charname + 10charname.o o.10charname + 11charname_.c c.11charname (assuming filesystem truncates at 10) + +The Unix emulation library's translation of filenames to native assumes +that this sort of translation is required, and allows a user defined list of +known suffixes which it will transpose in this fashion. This may appear +transparent, but consider that with these rules C and +C both map to C, and that C and +C cannot and do not attempt to emulate the reverse mapping. Other '.'s +in filenames are translated to '/'. + +S has "image files", files that behave as directories. For +example with suitable software this allows the contents of a zip file to +be treated as a directory at command line (and therefore script) level, +with full read-write random access. At present the perl port treats images +as directories: C<-d> returns true, C<-f> false, and C checks to +ensure that recognised images are empty before deleting them. In theory +images should never trouble a script, but in practice they may do so if +the software to deal with an image file is loaded and registered while the +script is running, as suddenly "files" that it had cached information on +metamorphose into directories. + +As implied above the environment accessed through C<%ENV> is global, and the +convention is that program specific environment variables are of the form +C. Each filing system maintains a current directory, and +the current filing system's current directory is the B current +directory. Consequently sociable scripts don't change the current directory +but rely on full pathnames, and scripts (and Makefiles) cannot assume that +they can spawn a child process which can change the current directory +without affecting its parent (and everyone else for that matter). + +As native operating system filehandles are global and currently are allocated +down from 255, with 0 being a reserved value the Unix emulation library +emulates Unix filehandles. Consequently you can't rely on passing C +C or C to your children. Run time libraries perform +command line processing to emulate Unix shell style C<>> redirection, but +the core operating system is written in assembler and has its own private, +obscure and somewhat broken convention. All this is further complicated by +the desire of users to express filenames of the form CFoo$DirE.Bar> on +the command line unquoted. (Oh yes, it's run time libraries interpreting the +quoting convention.) Hence C<``> command output capture has to perform +a guessing game as to how the command is going to interpret the command line +so that it can bodge it correctly to capture output. It assumes that a +string C[^EE]+\$[^EE]E> is a reference to an environment +variable, whereas anything else involving C> or C> is redirection, +and generally manages to be 99% right. Despite all this the problem remains +that scripts cannot rely on any Unix tools being available, or that any tools +found have Unix-like command line arguments. + +Extensions and XS are in theory buildable by anyone using free tools. In +practice many don't as the Acorn platform is used to binary distribution. +MakeMaker does itself run, but no make currently copes with MakeMaker's +makefiles! Even if (when) this is fixed os that the lack of a Unix-like +shell can cause problems with makefile rules, especially lines of the form +C and anything using quoting. + +"S" is the proper name for the operating system, but the value +in C<$^O> is "riscos" (because we don't like shouting). + +Also see: + +=over 4 + +=item perl list + +=back + + =head2 Other perls -Perl has been ported to a variety of platforms that do not fit into -any of the above categories. Some, such as AmigaOS, BeOS, MPE/iX, -OS/390 (MVS), QNX, and Plan 9, have been well integrated into the -standard Perl source code kit. You may need to see the F -directory on CPAN for information, and possibly binaries, for the -likes of: acorn, aos, atari, lynxos, riscos, Tandem Guardian, vos, -I (yes we know that some of these OSes may fall under the Unix -category but we are not a standards body.) +Perl has been ported to a variety of platforms that do not fit into any of +the above categories. Some, such as AmigaOS, BeOS, QNX, and Plan 9, have +been well integrated into the standard Perl source code kit. You may need +to see the F directory on CPAN for information, and possibly +binaries, for the likes of: aos, atari, lynxos, HP-MPE/iX, riscos, +Tandem Guardian, vos, I (yes we know that some of these OSes may fall +under the Unix category but we are not a standards body.) See also: @@ -743,14 +874,21 @@ considerations. C<-o> is not supported. (S) C<-r>, C<-w>, C<-x>, and C<-o> tell whether or not file is accessible, which may not reflect UIC-based file protections. (VMS) +C<-s> returns the size of the data fork, not the total size of data fork +plus resource fork. (S). + +C<-s> by name on an open file will return the space reserved on disk, +rather than the current extent. C<-s> on an open filehandle returns the +current size. (S) + C<-R>, C<-W>, C<-X>, C<-O> are indistinguishable from C<-r>, C<-w>, -C<-x>, C<-o>. (S, Win32, VMS) +C<-x>, C<-o>. (S, Win32, VMS, S) C<-b>, C<-c>, C<-k>, C<-g>, C<-p>, C<-u>, C<-A> are not implemented. (S) C<-g>, C<-k>, C<-l>, C<-p>, C<-u>, C<-A> are not particularly meaningful. -(Win32, VMS) +(Win32, VMS, S) C<-d> is true if passed a device spec without an explicit directory. (VMS) @@ -762,9 +900,12 @@ affects S a lot. (S) C<-x> (or C<-X>) determine if a file ends in one of the executable suffixes. C<-S> is meaningless. (Win32) +C<-x> (or C<-X>) determine if a file has an executable file type. +(S) + =item binmode FILEHANDLE -Meaningless. (S) +Meaningless. (S, S) Reopens file and restores pointer; if function fails, underlying filehandle may be closed, or pointer may be in a different position. @@ -781,9 +922,11 @@ locking/unlocking the file. (S) Only good for changing "owner" read-write access, "group", and "other" bits are meaningless. (Win32) +Only good for changing "owner" and "other" read-write access. (S) + =item chown LIST -Not implemented. (S, Win32, Plan9) +Not implemented. (S, Win32, Plan9, S) Does nothing, but won't fail. (Win32) @@ -791,12 +934,12 @@ Does nothing, but won't fail. (Win32) =item chroot -Not implemented. (S, Win32, VMS, Plan9) +Not implemented. (S, Win32, VMS, Plan9, S) =item crypt PLAINTEXT,SALT May not be available if library or source was not provided when building -perl. (Win32) +perl. (Win32) =item dbmclose HASH @@ -808,11 +951,11 @@ Not implemented. (VMS, Plan9) =item dump LABEL -Not useful. (S) +Not useful. (S, S) Not implemented. (Win32) -Invokes VMS debugger. (VMS) +Invokes VMS debugger. (VMS) =item exec LIST @@ -824,37 +967,39 @@ Not implemented. (Win32, VMS) =item flock FILEHANDLE,OPERATION -Not implemented (S, VMS). +Not implemented (S, VMS, S). Available only on Windows NT (not on Windows 95). (Win32) =item fork -Not implemented. (S, Win32, AmigaOS) +Not implemented. (S, Win32, AmigaOS, S) =item getlogin -Not implemented. (S) +Not implemented. (S, S) =item getpgrp PID -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item getppid -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item getpriority WHICH,WHO -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item getpwnam NAME Not implemented. (S, Win32) +Not useful. (S) + =item getgrnam NAME -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item getnetbyname NAME @@ -864,9 +1009,11 @@ Not implemented. (S, Win32, Plan9) Not implemented. (S, Win32) +Not useful. (S) + =item getgrgid GID -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item getnetbyaddr ADDR,ADDRTYPE @@ -906,27 +1053,27 @@ Not implemented. (Win32, Plan9) =item setpwent -Not implemented. (S, Win32) +Not implemented. (S, Win32, S) =item setgrent -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item sethostent STAYOPEN -Not implemented. (S, Win32, Plan9) +Not implemented. (S, Win32, Plan9, S) =item setnetent STAYOPEN -Not implemented. (S, Win32, Plan9) +Not implemented. (S, Win32, Plan9, S) =item setprotoent STAYOPEN -Not implemented. (S, Win32, Plan9) +Not implemented. (S, Win32, Plan9, S) =item setservent STAYOPEN -Not implemented. (Plan9, Win32) +Not implemented. (Plan9, Win32, S) =item endpwent @@ -934,7 +1081,7 @@ Not implemented. (S, Win32) =item endgrent -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item endhostent @@ -966,6 +1113,11 @@ Globbing built-in, but only C<*> and C metacharacters are supported. Features depend on external perlglob.exe or perlglob.bat. May be overridden with something like File::DosGlob, which is recommended. (Win32) +Globbing built-in, but only C<*> and C metacharacters are supported. +Globbing relies on operating system calls, which may return filenames in +any order. As most filesystems are case insensitive even "sorted" +filenames will not be in case sensitive order. (S) + =item ioctl FILEHANDLE,FUNCTION,SCALAR Not implemented. (VMS) @@ -973,16 +1125,18 @@ Not implemented. (VMS) Available only for socket handles, and it does what the ioctlsocket() call in the Winsock API does. (Win32) +Available only for socket handles. (S) + =item kill LIST -Not implemented. (S) +Not implemented, hence not useful for taint checking. (S, S) Available only for process handles returned by the C method of -spawning a process. (Win32) +spawning a process. (Win32) =item link OLDFILE,NEWFILE -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item lstat FILEHANDLE @@ -990,9 +1144,9 @@ Not implemented. (S, Win32, VMS) =item lstat -Not implemented. (VMS) +Not implemented. (VMS, S) -Return values may be bogus. (Win32) +Return values may be bogus. (Win32) =item msgctl ID,CMD,ARG @@ -1002,7 +1156,7 @@ Return values may be bogus. (Win32) =item msgrcv ID,VAR,SIZE,TYPE,FLAGS -Not implemented. (S, Win32, VMS, Plan9) +Not implemented. (S, Win32, VMS, Plan9, S) =item open FILEHANDLE,EXPR @@ -1011,7 +1165,7 @@ Not implemented. (S, Win32, VMS, Plan9) The C<|> variants are only supported if ToolServer is installed. (S) -open to C<|-> and C<-|> are unsupported. (S, Win32) +open to C<|-> and C<-|> are unsupported. (S, Win32, S) =item pipe READHANDLE,WRITEHANDLE @@ -1021,27 +1175,29 @@ Not implemented. (S) =item readlink -Not implemented. (Win32, VMS) +Not implemented. (Win32, VMS, S) =item select RBITS,WBITS,EBITS,TIMEOUT Only implemented on sockets. (Win32) +Only reliable on sockets. (S) + =item semctl ID,SEMNUM,CMD,ARG =item semget KEY,NSEMS,FLAGS =item semop KEY,OPSTRING -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item setpgrp PID,PGRP -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item setpriority WHICH,WHO,PRIORITY -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL @@ -1055,11 +1211,11 @@ Not implemented. (S, Plan9) =item shmwrite ID,STRING,POS,SIZE -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item stat FILEHANDLE @@ -1074,13 +1230,16 @@ device and inode are not meaningful. (Win32) device and inode are not necessarily reliable. (VMS) +mtime, atime and ctime all return the last modification time. Device and +inode are not necessarily reliable. (S) + =item symlink OLDFILE,NEWFILE -Not implemented. (Win32, VMS) +Not implemented. (Win32, VMS, S) =item syscall LIST -Not implemented. (S, Win32, VMS) +Not implemented. (S, Win32, VMS, S) =item system LIST @@ -1092,6 +1251,16 @@ process and immediately returns its process designator, without waiting for it to terminate. Return value may be used subsequently in C or C. (Win32) +There is no shell to process metacharacters, and the native standard is +to pass a command line terminated by "\n" "\r" or "\0" to the spawned +program. Redirection such as C foo> is performed (if at all) by +the run time library of the spawned program. C I will call +the Unix emulation library's C emulation, which attempts to provide +emulation of the stdin, stdout, stderr in force in the parent, providing +the child program uses a compatible version of the emulation library. +I will call the native command line direct and no such emulation +of a child Unix program will exists. Mileage B vary. (S) + =item times Only the first entry returned is nonzero. (S) @@ -1100,6 +1269,8 @@ Only the first entry returned is nonzero. (S) "system" time will be bogus, and "user" time is actually the time returned by the clock() function in the C runtime library. (Win32) +Not useful. (S) + =item truncate FILEHANDLE,LENGTH =item truncate EXPR,LENGTH @@ -1114,7 +1285,7 @@ Returns undef where unavailable, as of version 5.005. =item utime LIST -Only the modification time is updated. (S, VMS) +Only the modification time is updated. (S, VMS, S) May not behave as expected. (Win32) @@ -1127,8 +1298,23 @@ Not implemented. (S) Can only be applied to process handles returned for processes spawned using C. (Win32) +Not useful. (S) + =back +=head1 CHANGES + +=over 4 + +=item 1.30, 03 August 1998 + +Major update for RISC OS, other minor changes. + +=item 1.23, 10 July 1998 + +First public release with perl5.005. + +=back =head1 AUTHORS / CONTRIBUTORS @@ -1151,11 +1337,12 @@ Dan Sugalski Esugalskd@ous.eduE, Andreas J. Koenig Ekoenig@kulturbox.deE, Andrew M. Langmead Eaml@world.std.comE, Andy Dougherty Edoughera@lafcol.lafayette.eduE, -Abigail Eabigail@fnx.comE. +Abigail Eabigail@fnx.comE, +Nicholas Clark ENicholas.Clark@liverpool.ac.ukE. This document is maintained by Chris Nandor. =head1 VERSION -Version 1.23, last modified 10 July 1998. +Version 1.30, last modified 03 August 1998.