Reorder perl.pod once more.
[p5sagit/p5-mst-13.2.git] / pod / perlport.pod
index 0518478..7f779c9 100644 (file)
@@ -197,7 +197,7 @@ If you need to distinguish between endian architectures you could use
 either of the variables set like so:
 
     $is_big_endian   = unpack("h*", pack("s", 1)) =~ /01/;
-    $is_litte_endian = unpack("h*", pack("s", 1)) =~ /^1/;
+    $is_little_endian = unpack("h*", pack("s", 1)) =~ /^1/;
 
 Differing widths can cause truncation even between platforms of equal
 endianness.  The platform of shorter width loses the upper parts of the
@@ -217,7 +217,7 @@ So, it is reasonably safe to assume that all platforms support the
 notion of a "path" to uniquely identify a file on the system.  How
 that path is really written, though, differs considerably.
 
-Atlhough similar, file path specifications differ between Unix,
+Although similar, file path specifications differ between Unix,
 Windows, S<Mac OS>, OS/2, VMS, VOS, S<RISC OS>, and probably others.
 Unix, for example, is one of the few OSes that has the elegant idea
 of a single root directory.
@@ -355,7 +355,7 @@ Commands that launch external processes are generally supported on
 most platforms (though many of them do not support any type of
 forking).  The problem with using them arises from what you invoke
 them on.  External tools are often named differently on different
-platforms, may not be available in the same location, migth accept
+platforms, may not be available in the same location, might accept
 different arguments, can behave differently, and often present their
 results in a platform-dependent way.  Thus, you should seldom depend
 on them to produce consistent results. (Then again, if you're calling 
@@ -528,7 +528,7 @@ a given module works on a given platform.
 
 =item Mailing list: cpan-testers@perl.org
 
-=item Testing results: C<http://testers.cpan.org/>
+=item Testing results: http://testers.cpan.org/
 
 =back
 
@@ -654,21 +654,41 @@ Also see:
 
 =over 4
 
-=item The djgpp environment for DOS, C<http://www.delorie.com/djgpp/>
+=item *
 
-=item The EMX environment for DOS, OS/2, etc. C<emx@iaehv.nl>,
-C<http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html> or
-C<ftp://hobbes.nmsu.edu/pub/os2/dev/emx>
+The djgpp environment for DOS, http://www.delorie.com/djgpp/
+and L<perldos>.
 
-=item Build instructions for Win32, L<perlwin32>.
+=item *
 
-=item The ActiveState Pages, C<http://www.activestate.com/>
+The EMX environment for DOS, OS/2, etc. emx@iaehv.nl,
+http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/index.html or
+ftp://hobbes.nmsu.edu/pub/os2/dev/emx.  Also L<perlos2>.
 
-=item The Cygwin environment for Win32; F<README.cygwin> (installed 
-as L<perlcygwin>), C<http://sourceware.cygnus.com/cygwin/>
+=item *
 
-=item The U/WIN environment for Win32,
-C<http://www.research.att.com/sw/tools/uwin/>
+Build instructions for Win32 in L<perlwin32>, or under the Cygnus environment
+in L<perlcygwin>.  
+
+=item *
+
+The C<Win32::*> modules in L<Win32>.
+
+=item *
+
+The ActiveState Pages, http://www.activestate.com/
+
+=item *
+
+The Cygwin environment for Win32; F<README.cygwin> (installed 
+as L<perlcygwin>), http://sourceware.cygnus.com/cygwin/
+
+=item *
+
+The U/WIN environment for Win32,
+<http://www.research.att.com/sw/tools/uwin/
+
+=item Build instructions for OS/2, L<perlos2>
 
 
 =back
@@ -742,17 +762,23 @@ Also see:
 
 =over 4
 
-=item The MacPerl Pages, C<http://www.macperl.com/>.
+=item *
+
+The MacPerl Pages, http://www.macperl.com/ .
+
+=item *
 
-=item The MacPerl mailing lists, C<http://www.macperl.org/>.
+The MacPerl mailing lists, http://www.macperl.org/ .
 
-=item MacPerl Module Porters, C<http://pudge.net/mmp/>.
+=item *
+
+MacPerl Module Porters, http://pudge.net/mmp/ .
 
 =back
 
 =head2 VMS
 
-Perl on VMS is discussed in F<vms/perlvms.pod> in the perl distribution.
+Perl on VMS is discussed in L<perlvms> in the perl distribution.
 Perl on VMS can accept either VMS- or Unix-style file
 specifications as in either of the following:
 
@@ -844,13 +870,19 @@ Also see:
 
 =over 4
 
-=item F<README.vms> (installed as L<README_vms>), L<perlvms>
+=item *
+
+F<README.vms> (installed as L<README_vms>), L<perlvms>
+
+=item *
 
-=item vmsperl list, C<majordomo@perl.org>
+vmsperl list, majordomo@perl.org
 
-Put the words C<subscribe vmsperl> in message body.
+(Put the words C<subscribe vmsperl> in message body.)
 
-=item vmsperl on the web, C<http://www.sidhe.org/vmsperl/index.html>
+=item *
+
+vmsperl on the web, http://www.sidhe.org/vmsperl/index.html
 
 =back
 
@@ -883,7 +915,7 @@ ftp.stratus.com.
 
 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
-can examine the content of the C<@INC> array like so:
+can examine the content of the @INC array like so:
 
     if ($^O =~ /VOS/) {
         print "I'm on a Stratus box!\n";
@@ -909,16 +941,22 @@ Also see:
 
 =over 4
 
-=item F<README.vos>
+=item *
+
+F<README.vos>
 
-=item VOS mailing list
+=item *
+
+The VOS mailing list.
 
 There is no specific mailing list for Perl on VOS.  You can post
 comments to the comp.sys.stratus newsgroup, or subscribe to the general
 Stratus mailing list.  Send a letter with "Subscribe Info-Stratus" in
 the message body to majordomo@list.stratagy.com.
 
-=item VOS Perl on the web at C<http://ftp.stratus.com/pub/vos/vos.html>
+=item *
+
+VOS Perl on the web at http://ftp.stratus.com/pub/vos/vos.html
 
 =back
 
@@ -931,6 +969,7 @@ Character Code Set ID 0037 for OS/400 and either 1047 or POSIX-BC for S/390
 systems).  On the mainframe perl currently works under the "Unix system
 services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or
 the BS200 POSIX-BC system (BS2000 is supported in perl 5.6 and greater).
+See L<perlos390> for details.  
 
 As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
 sub-systems do not support the C<#!> shebang trick for script invocation.
@@ -999,15 +1038,22 @@ Also see:
 
 =over 4
 
-=item F<README.os390>, F<README.posix-bc>, F<README.vmesa>
+=item *
+
+*
 
-=item perl-mvs list
+L<perlos390>, F<README.os390>, F<README.posix-bc>, F<README.vmesa>
+
+=item *
 
 The perl-mvs@perl.org list is for discussion of porting issues as well as
 general usage issues for all EBCDIC Perls.  Send a message body of
 "subscribe perl-mvs" to majordomo@perl.org.
 
-=item AS/400 Perl information at C<http://as400.rochester.ibm.com/>
+=item  *
+
+AS/400 Perl information at
+ttp://as400.rochester.ibm.com/
 as well as on CPAN in the F<ports/> directory.
 
 =back
@@ -1138,23 +1184,33 @@ See also:
 
 =over 4
 
-=item Amiga, F<README.amiga> (installed as L<perlamiga>).
+=item *
 
-=item Atari, F<README.mint> and Guido Flohr's web page
-C<http://stud.uni-sb.de/~gufl0000/>
+Amiga, F<README.amiga> (installed as L<perlamiga>).
 
-=item Be OS, F<README.beos>
+=item *
 
-=item HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page
-C<http://www.cccd.edu/~markb/perlix.html>
+Atari, F<README.mint> and Guido Flohr's web page
+http://stud.uni-sb.de/~gufl0000/
 
-=item Novell Netware
+=item *
+
+Be OS, F<README.beos>
+
+=item *
+
+HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page
+http://www.cccd.edu/~markb/perlix.html
+
+=item *
 
 A free perl5-based PERL.NLM for Novell Netware is available in
-precompiled binary and source code form from C<http://www.novell.com/>
+precompiled binary and source code form from http://www.novell.com/
 as well as from CPAN.
 
-=item Plan 9, F<README.plan9>
+=item 
+
+Plan 9, F<README.plan9>
 
 =back
 
@@ -1223,6 +1279,12 @@ suffixes.  C<-S> is meaningless.  (Win32)
 C<-x> (or C<-X>) determine if a file has an executable file type.
 (S<RISC OS>)
 
+=item alarm SECONDS
+
+=item alarm
+
+Not implemented. (Win32)
+
 =item binmode FILEHANDLE
 
 Meaningless.  (S<Mac OS>, S<RISC OS>)
@@ -1444,14 +1506,8 @@ Not implemented. (S<Mac OS>, Plan9)
 Globbing built-in, but only C<*> and C<?> metacharacters are supported.
 (S<Mac OS>)
 
-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<RISC OS>)
+This operator is implemented via the File::Glob extension on most
+platforms.  See L<File::Glob> for portability information.
 
 =item ioctl FILEHANDLE,FUNCTION,SCALAR
 
@@ -1467,9 +1523,12 @@ Available only for socket handles. (S<RISC OS>)
 Not implemented, hence not useful for taint checking. (S<Mac OS>,
 S<RISC OS>)
 
-C<kill($sig, $pid)> makes the process exit immediately with exit
-status $sig.  As in Unix, if $sig is 0 and the specified process exists,
-it returns true without actually terminating it. (Win32)
+C<kill()> doesn't have the semantics of C<raise()>, i.e. it doesn't send
+a signal to the identified process like it does on Unix platforms.
+Instead C<kill($sig, $pid)> terminates the process identified by $pid,
+and makes it exit immediately with exit status $sig.  As in Unix, if
+$sig is 0 and the specified process exists, it returns true without
+actually terminating it. (Win32)
 
 =item link OLDFILE,NEWFILE
 
@@ -1489,7 +1548,7 @@ under NTFS only.
 
 Not implemented. (VMS, S<RISC OS>)
 
-Return values may be bogus. (Win32)
+Return values (especially for device and inode) may be bogus. (Win32)
 
 =item msgctl ID,CMD,ARG
 
@@ -1531,6 +1590,8 @@ Only implemented on sockets. (Win32)
 
 Only reliable on sockets. (S<RISC OS>)
 
+Note that the C<socket FILEHANDLE> form is generally portable.
+
 =item semctl ID,SEMNUM,CMD,ARG
 
 =item semget KEY,NSEMS,FLAGS
@@ -1612,7 +1673,10 @@ As an optimization, may not call the command shell specified in
 C<$ENV{PERL5SHELL}>.  C<system(1, @args)> spawns an external
 process and immediately returns its process designator, without
 waiting for it to terminate.  Return value may be used subsequently
-in C<wait> or C<waitpid>.  (Win32)
+in C<wait> or C<waitpid>.  Failure to spawn() a subprocess is indicated
+by setting $? to "255 << 8".  C<$?> is set in a way compatible with
+Unix (i.e. the exitstatus of the subprocess is obtained by "$? >> 8",
+as described in the documentation).  (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
@@ -1636,9 +1700,10 @@ Does not automatically flush output handles on some platforms.
 
 Only the first entry returned is nonzero. (S<Mac OS>)
 
-"cumulative" times will be bogus.  On anything other than Windows NT,
-"system" time will be bogus, and "user" time is actually the time
-returned by the clock() function in the C runtime library. (Win32)
+"cumulative" times will be bogus.  On anything other than Windows NT
+or Windows 2000, "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<RISC OS>)
 
@@ -1691,6 +1756,11 @@ Not useful. (S<RISC OS>)
 
 =over 4
 
+=item v1.47, 22 March 2000
+
+Various cleanups from Tom Christiansen, including migration of 
+long platform listings from L<perl>.
+
 =item v1.46, 12 February 2000
 
 Updates for VOS and MPE/iX. (Peter Prymmer)  Other small changes.
@@ -1774,6 +1844,7 @@ distribution available at http://www.perl.com/CPAN/src/index.html
 
        AIX
        DOS DJGPP       1)
+       EPOC
        FreeBSD
        HP-UX
        IRIX
@@ -1784,11 +1855,16 @@ distribution available at http://www.perl.com/CPAN/src/index.html
        NetBSD
        OpenBSD
        OS/2
+       QNX
        Rhapsody/Darwin 2)
+       SCO SV
+       SINIX
        Solaris
+       SVR4
        Tru64 UNIX      3)
        UNICOS
        UNICOS/mk
+       Unixware
        VMS
        VOS
        Windows 3.1     1)
@@ -1817,10 +1893,8 @@ just fine with 5.6.0.
        NextSTEP
        OpenSTEP
        PowerMAX
-       QNX
        SCO ODT/OSR     
        SunOS
-       SVR4
        Ultrix
 
 The following platform worked for the previous major release (5.005_03
@@ -1845,7 +1919,7 @@ as OS390.  Contact the mailing list perl-mvs@perl.org for more details.
 MacOS (Classic, pre-X) is almost 5.6.0-ready; building from the source
 does work with 5.6.0, but additional MacOS specific source code is needed
 for a complete port.  Contact the mailing list macperl-porters@macperl.org
-for more more information.
+for more information.
 
 The following platforms have been known to build Perl from source in
 the past, but we haven't been able to verify their status for the
@@ -1896,7 +1970,7 @@ binaries available via http://www.perl.com/CPAN/ports/index.html:
        Tandem Guardian         5.004
 
 The following platforms have only binaries available via
-http://www.perl.com/CPAN/ports/index.html:
+http://www.perl.com/CPAN/ports/index.html :
 
                                Perl release
 
@@ -1909,6 +1983,11 @@ the source code, both for maximal configurability and for security,
 in case you are in a hurry you can check
 http://www.perl.com/CPAN/ports/index.html for binary distributions.
 
+=head1 SEE ALSO
+
+L<perlamiga>, L<perlcygwin>, L<perldos>, L<perlhpux>, L<perlos2>,
+L<perlos390>, L<perlwin32>, L<perlvms>, and L<Win32>.
+
 =head1 AUTHORS / CONTRIBUTORS
 
 Abigail <abigail@fnx.com>,
@@ -1949,4 +2028,4 @@ This document is maintained by Chris Nandor
 
 =head1 VERSION
 
-Version 1.46, last modified 12 February 2000
+Version 1.47, last modified 22 March 2000