X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlport.pod;h=3b11a4f45eeebe8403908636098ee4db99a0e852;hb=ba370e9b8a212c313d985163053c7ed938fcae22;hp=ae9e0c2a1094edcb0d3b3f498a58497f26e0b3ad;hpb=b84d4f81fd7f50ce896c753a15a85cba48f9ed80;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlport.pod b/pod/perlport.pod index ae9e0c2..3b11a4f 100644 --- a/pod/perlport.pod +++ b/pod/perlport.pod @@ -94,6 +94,26 @@ from) C<\015\012>, depending on whether you're reading or writing. Unix does the same thing on ttys in canonical mode. C<\015\012> is commonly referred to as CRLF. +A common cause of unportable programs is the misuse of chop() to trim +newlines: + + # XXX UNPORTABLE! + while() { + chop; + @array = split(/:/); + #... + } + +You can get away with this on Unix and MacOS (they have a single +character end-of-line), but the same program will break under DOSish +perls because you're only chop()ing half the end-of-line. Instead, +chomp() should be used to trim newlines. The Dunce::Files module can +help audit your code for misuses of chop(). + +When dealing with binary files (or text files in binary mode) be sure +to explicitly set $/ to the appropriate value for your file format +before using chomp(). + Because of the "text" mode translation, DOSish perls have limitations in using C and C on a file accessed in "text" mode. Stick to C-ing to locations you got from C (and no @@ -209,8 +229,8 @@ transferring or storing raw binary numbers. One can circumnavigate both these problems in two ways. Either transfer and store numbers always in text format, instead of raw binary, or else consider using modules like Data::Dumper (included in -the standard distribution as of Perl 5.005) and Storable. Keeping -all data as text significantly simplifies matters. +the standard distribution as of Perl 5.005) and Storable (included as +of perl 5.8). Keeping all data as text significantly simplifies matters. =head2 Files and Filesystems @@ -332,9 +352,31 @@ file already tied or opened; C or C it first. Don't open the same file more than once at a time for writing, as some operating systems put mandatory locks on such files. +Don't assume that write/modify permission on a directory gives the +right to add or delete files/directories in that directory. That is +filesystem specific: in some filesystems you need write/modify +permission also (or even just) in the file/directory itself. In some +filesystems (AFS, DFS) the permission to add/delete directory entries +is a completely separate permission. + +Don't assume that a single C completely gets rid of the file: +some filesystems (most notably the ones in VMS) have versioned +filesystems, and unlink() removes only the most recent one (it doesn't +remove all the versions because by default the native tools on those +platforms remove just the most recent version, too). The portable +idiom to remove all the versions of a file is + + 1 while unlink "file"; + +This will terminate if the file is undeleteable for some reason +(protected, not there, and so on). + Don't count on a specific environment variable existing in C<%ENV>. Don't count on C<%ENV> entries being case-sensitive, or even -case-preserving. +case-preserving. Don't try to clear %ENV by saying C<%ENV = ();>, or, +if you really have to, make it conditional on C<$^O ne 'VMS'> since in +VMS the C<%ENV> table is much more than a per-process key-value string +table. Don't count on signals or C<%SIG> for anything. @@ -381,6 +423,14 @@ simple, platform-independent mailing. The Unix System V IPC (C) is not available even on all Unix platforms. +Do not use either the bare result of C or +bare v-strings (such as C) to represent IPv4 addresses: +both forms just pack the four bytes into network order. That this +would be equal to the C language C struct (which is what the +socket code internally uses) is not guaranteed. To be portable use +the routines of the Socket extension, such as C, +C, and C. + The rule of thumb for portable code is: Do it all in portable Perl, or use a module (that may internally implement it with platform-specific code, but expose a common interface). @@ -509,7 +559,7 @@ often happens when tests spawn off other processes or call external programs to aid in the testing, or when (as noted above) the tests assume certain things about the filesystem and paths. Be careful not to depend on a specific output style for errors, such as when -checking C<$!> after an system call. Some platforms expect a certain +checking C<$!> after a system call. Some platforms expect a certain output format, and perl on those platforms may have been adjusted accordingly. Most specifically, don't anchor a regex when testing an error value. @@ -572,7 +622,7 @@ are a few of the more popular Unix flavors: Linux linux ppc-linux HP-UX hpux PA-RISC1.1 IRIX irix irix - Mac OS X rhapsody rhapsody + Mac OS X darwin darwin MachTen PPC machten powerpc-machten NeXT 3 next next-fat NeXT 4 next OPENSTEP-Mach @@ -640,17 +690,31 @@ often assume nothing about their data. The C<$^O> variable and the C<$Config{archname}> values for various DOSish perls are as follows: - OS $^O $Config{'archname'} - -------------------------------------------- - MS-DOS dos - PC-DOS dos - OS/2 os2 - Windows 95 MSWin32 MSWin32-x86 - Windows 98 MSWin32 MSWin32-x86 - Windows NT MSWin32 MSWin32-x86 - Windows NT MSWin32 MSWin32-ALPHA - Windows NT MSWin32 MSWin32-ppc - Cygwin cygwin + OS $^O $Config{archname} ID Version + -------------------------------------------------------- + MS-DOS dos ? + PC-DOS dos ? + OS/2 os2 ? + Windows 3.1 ? ? 0 3 01 + Windows 95 MSWin32 MSWin32-x86 1 4 00 + Windows 98 MSWin32 MSWin32-x86 1 4 10 + Windows ME MSWin32 MSWin32-x86 1 ? + Windows NT MSWin32 MSWin32-x86 2 4 xx + Windows NT MSWin32 MSWin32-ALPHA 2 4 xx + Windows NT MSWin32 MSWin32-ppc 2 4 xx + Windows 2000 MSWin32 MSWin32-x86 2 5 xx + Windows XP MSWin32 MSWin32-x86 2 ? + Windows CE MSWin32 ? 3 + Cygwin cygwin ? + +The various MSWin32 Perl's can distinguish the OS they are running on +via the value of the fifth element of the list returned from +Win32::GetOSVersion(). For example: + + if ($^O eq 'MSWin32') { + my @os_version_info = Win32::GetOSVersion(); + print +('3.1','95','NT')[$os_version_info[4]],"\n"; + } Also see: @@ -683,15 +747,16 @@ The ActiveState Pages, http://www.activestate.com/ =item * The Cygwin environment for Win32; F (installed -as L), http://sources.redhat.com/cygwin/ +as L), http://www.cygwin.com/ =item * The U/WIN environment for Win32, - +=item * +Build instructions for OS/2, L =back @@ -751,14 +816,10 @@ the application or MPW tool version is running, check: $is_ppc = $MacPerl::Architecture eq 'MacPPC'; $is_68k = $MacPerl::Architecture eq 'Mac68K'; -S and S, based on NeXT's OpenStep OS, will -(in theory) be able to run MacPerl natively, under the "Classic" -environment. The new "Cocoa" environment (formerly called the "Yellow Box") -may run a slightly modified version of MacPerl, using the Carbon interfaces. - -S and its Open Source version, Darwin, both run Unix -perl natively (with a few patches). Full support for these -is slated for perl 5.6. +S, based on NeXT's OpenStep OS, runs MacPerl natively, under the +"Classic" environment. There is no "Carbon" version of MacPerl to run +under the primary Mac OS X environment. S and its Open Source +version, Darwin, both run Unix perl natively. Also see: @@ -766,15 +827,15 @@ Also see: =item * -The MacPerl Pages, http://www.macperl.com/ . +MacPerl Development, http://dev.macperl.org/ . =item * -The MacPerl mailing lists, http://www.macperl.org/ . +The MacPerl Pages, http://www.macperl.com/ . =item * -MacPerl Module Porters, http://pudge.net/mmp/ . +The MacPerl mailing lists, http://lists.perl.org/ . =back @@ -841,10 +902,11 @@ process on VMS, is a pure Perl module that can easily be installed on non-VMS platforms and can be helpful for conversions to and from RMS native formats. -What C<\n> represents depends on the type of file opened. It could -be C<\015>, C<\012>, C<\015\012>, or nothing. The VMS::Stdio module -provides access to the special fopen() requirements of files with unusual -attributes on VMS. +What C<\n> represents depends on the type of file opened. It usually +represents C<\012> but it could also be C<\015>, C<\012>, C<\015\012>, +C<\000>, C<\040>, or nothing depending on the file organiztion and +record format. The VMS::Stdio module provides access to the +special fopen() requirements of files with unusual attributes on VMS. TCP/IP stacks are optional on VMS, so socket routines might not be implemented. UDP sockets may not be supported. @@ -890,9 +952,9 @@ vmsperl on the web, http://www.sidhe.org/vmsperl/index.html =head2 VOS -Perl on VOS is discussed in F in the perl distribution. -Perl on VOS can accept either VOS- or Unix-style file -specifications as in either of the following: +Perl on VOS is discussed in F in the perl distribution +(installed as L). Perl on VOS can accept either VOS- or +Unix-style file specifications as in either of the following: $ perl -ne "print if /perl_setup/i" >system>notices $ perl -ne "print if /perl_setup/i" /system/notices @@ -908,12 +970,11 @@ contain a slash character cannot be processed. Such files must be renamed before they can be processed by Perl. Note that VOS limits file names to 32 or fewer characters. -The following C functions are unimplemented on VOS, and any attempt by -Perl to use them will result in a fatal error message and an immediate -exit from Perl: dup, do_aspawn, do_spawn, fork, waitpid. Once these -functions become available in the VOS POSIX.1 implementation, you can -either recompile and rebind Perl, or you can download a newer port from -ftp.stratus.com. +See F for restrictions that apply when Perl is built +with the alpha version of VOS POSIX.1 support. + +Perl on VOS is built without any extensions and does not support +dynamic loading. The value of C<$^O> on VOS is "VOS". To determine the architecture that you are running on without resorting to loading all of C<%Config> you @@ -1044,7 +1105,7 @@ Also see: * -L, F, F, F, +L, F, F, F, L. =item * @@ -1056,7 +1117,7 @@ general usage issues for all EBCDIC Perls. Send a message body of =item * AS/400 Perl information at -ttp://as400.rochester.ibm.com/ +http://as400.rochester.ibm.com/ as well as on CPAN in the F directory. =back @@ -1203,7 +1264,7 @@ Be OS, F =item * HP 300 MPE/iX, F and Mark Bixby's web page -http://www.cccd.edu/~markb/perlix.html +http://www.bixby.org/mark/perlix.html =item * @@ -1211,7 +1272,7 @@ A free perl5-based PERL.NLM for Novell Netware is available in precompiled binary and source code form from http://www.novell.com/ as well as from CPAN. -=item +=item * Plan 9, F @@ -1355,6 +1416,17 @@ Implemented via Spawn. (VM/ESA) Does not automatically flush output handles on some platforms. (SunOS, Solaris, HP-UX) +=item exit EXPR + +=item exit + +Emulates UNIX exit() (which considers C to indicate an error) by +mapping the C<1> to SS$_ABORT (C<44>). This behavior may be overridden +with the pragma C. As with the CRTL's exit() +function, C is also mapped to an exit status of SS$_NORMAL +(C<1>); this mapping cannot be overridden. Any other argument to exit() +is used directly as Perl's exit status. (VMS) + =item fcntl FILEHANDLE,FUNCTION,SCALAR Not implemented. (Win32, VMS) @@ -1500,15 +1572,12 @@ Not implemented. (Plan9, Win32) =item getsockopt SOCKET,LEVEL,OPTNAME -Not implemented. (S, Plan9) +Not implemented. (Plan9) =item glob EXPR =item glob -Globbing built-in, but only C<*> and C metacharacters are supported. -(S) - This operator is implemented via the File::Glob extension on most platforms. See L for portability information. @@ -1523,8 +1592,10 @@ Available only for socket handles. (S) =item kill SIGNAL, LIST -Not implemented, hence not useful for taint checking. (S, -S) +C is implemented for the sake of taint checking; +use with other signals is unimplemented. (S) + +Not implemented, hence not useful for taint checking. (S) C doesn't have the semantics of C, i.e. it doesn't send a signal to the identified process like it does on Unix platforms. @@ -1577,8 +1648,6 @@ platforms. (SunOS, Solaris, HP-UX) =item pipe READHANDLE,WRITEHANDLE -Not implemented. (S) - Very limited functionality. (MiNT) =item readlink EXPR @@ -1589,11 +1658,11 @@ Not implemented. (Win32, VMS, S) =item select RBITS,WBITS,EBITS,TIMEOUT -Only implemented on sockets. (Win32) +Only implemented on sockets. (Win32, VMS) Only reliable on sockets. (S) -Note that the C form is generally portable. +Note that the C