Regen toc.
[p5sagit/p5-mst-13.2.git] / pod / perlport.pod
index ef05ecf..2b4d3d9 100644 (file)
@@ -75,7 +75,7 @@ This information should not be considered complete; it includes possibly
 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
-(<IMG SRC="yellow_sign.gif" ALT="Under Construction">).
+(C<< <IMG SRC="yellow_sign.gif" ALT="Under Construction"> >>).
 
 =head1 ISSUES
 
@@ -171,8 +171,8 @@ newline representation.  A single line of code will often suffice:
 Some of this may be confusing.  Here's a handy reference to the ASCII CR
 and LF characters.  You can print it out and stick it in your wallet.
 
-    LF  ==  \012  ==  \x0A  ==  \cJ  ==  ASCII 10
-    CR  ==  \015  ==  \x0D  ==  \cM  ==  ASCII 13
+    LF  eq  \012  eq  \x0A  eq  \cJ  eq  chr(10)  eq  ASCII 10
+    CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  ASCII 13
 
              | Unix | DOS  | Mac  |
         ---------------------------
@@ -188,7 +188,23 @@ The Unix column assumes that you are not accessing a serial line
 "\n", and "\n" on output becomes CRLF.
 
 These are just the most common definitions of C<\n> and C<\r> in Perl.
-There may well be others.
+There may well be others.  For example, on an EBCDIC implementation such
+as z/OS or OS/400 the above material is similar to "Unix" but the code
+numbers change:
+
+    LF  eq  \025  eq  \x15  eq           chr(21)  eq  CP-1047 21
+    LF  eq  \045  eq  \x25  eq  \cU  eq  chr(37)  eq  CP-0037 37
+    CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  CP-1047 13
+    CR  eq  \015  eq  \x0D  eq  \cM  eq  chr(13)  eq  CP-0037 13
+
+             | z/OS | OS/400 |
+        ----------------------
+        \n   |  LF  |  LF    |
+        \r   |  CR  |  CR    |
+        \n * |  LF  |  LF    |
+        \r * |  CR  |  CR    |
+        ----------------------
+        * text-mode STDIO
 
 =head2 Numbers endianness and Width
 
@@ -262,7 +278,7 @@ timestamp (meaning that about the only portable timestamp is the
 modification timestamp), or one second granularity of any timestamps
 (e.g. the FAT filesystem limits the time granularity to two seconds).
 
-The "inode change timestamp" (the <-C> filetest) may really be the
+The "inode change timestamp" (the C<-C> filetest) may really be the
 "creation timestamp" (which it is not in UNIX).
 
 VOS perl can emulate Unix filenames with C</> as path separator.  The
@@ -432,6 +448,36 @@ directories.
 
 Don't count on specific values of C<$!>.
 
+=head2 Command names versus file pathnames
+
+Don't assume that the name used to invoke a command or program with
+C<system> or C<exec> can also be used to test for the existence of the
+file that holds the executable code for that command or program.
+First, many operating systems have "internal" commands that are
+built-in to the OS and while these commands can be invoked, there is
+no corresponding file.  Second, some operating systems (Cygwin, DJGPP,
+OS/2, and VOS) have required suffixes for executable files; these
+suffixes are generally permitted on the command name but are not
+required.  Thus, a command like "perl" might exist in a file named
+"perl", "perl.exe", or "perl.pm", depending on the operating system.
+The variable "_exe" in the Config module holds the executable suffix,
+if any.  Third, VMS files always end in a version number, which comes
+after the executable suffix.
+
+To convert $^X to a file pathname, taking account of the requirements
+of the various operating system possibilities, say:
+  use Config;
+  use File::Spec;
+  $thisperl = $^X;
+  $thisperl .= $Config{_exe} unless $thisperl ~= m/$Config{_exe}([;\d]*)$/i;
+
+To convert $Config{perlpath} to a file pathname, say:
+
+  use Config;
+  use File::Spec;
+  $thisperl = File::Spec->canonpath($Config{perlpath});
+  $thisperl .= $Config{_exe} unless $thisperl ~= m/$Config{_exe}([;\d]*)$/i;
+
 =head2 Interprocess Communication (IPC)
 
 In general, don't directly access the system in code meant to be
@@ -797,7 +843,7 @@ and L<perldos>.
 
 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>.
+ftp://hobbes.nmsu.edu/pub/os2/dev/emx/  Also L<perlos2>.
 
 =item *
 
@@ -1024,12 +1070,12 @@ Perl on VOS is discussed in F<README.vos> in the perl distribution
 (installed as L<perlvos>).  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
+    C<< $ perl -ne "print if /perl_setup/i" >system>notices >>
+    C<< $ perl -ne "print if /perl_setup/i" /system/notices >>
 
 or even a mixture of both as in:
 
-    $ perl -ne "print if /perl_setup/i" >system/notices
+    C<< $ perl -ne "print if /perl_setup/i" >system/notices >>
 
 Even though VOS allows the slash character to appear in object
 names, because the VOS port of Perl interprets it as a pathname
@@ -1038,11 +1084,12 @@ 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.
 
-See F<README.vos> 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.
+Perl on VOS can be built using two different compilers and two different
+versions of the POSIX runtime.  The recommended method for building full
+Perl is with the GNU C compiler and the generally-available version of
+VOS POSIX support.  See F<README.vos> (installed as L<perlvos>) for
+restrictions that apply when Perl is built using the VOS Standard C
+compiler or the alpha version of VOS POSIX support.
 
 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
@@ -1074,7 +1121,7 @@ Also see:
 
 =item *
 
-F<README.vos>
+F<README.vos> (installed as L<perlvos>)
 
 =item *
 
@@ -1082,12 +1129,12 @@ 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
+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 http://ftp.stratus.com/pub/vos/vos.html
+VOS Perl on the web at http://ftp.stratus.com/pub/vos/posix/posix.html
 
 =back
 
@@ -1593,14 +1640,6 @@ Not implemented. (S<Mac OS>, Win32, Plan9)
 
 Not implemented. (Win32, Plan9)
 
-=item setpwent
-
-Not implemented. (S<Mac OS>, Win32, S<RISC OS>)
-
-=item setgrent
-
-Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
-
 =item sethostent STAYOPEN
 
 Not implemented. (S<Mac OS>, Win32, Plan9, S<RISC OS>)
@@ -1745,7 +1784,7 @@ Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
 =item setgrent
 
-Not implemented. (MPE/iX, Win32)
+Not implemented. (S<Mac OS>, MPE/iX, VMS, Win32, VMS, S<RISC OS>)
 
 =item setpgrp PID,PGRP
 
@@ -1757,7 +1796,7 @@ Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
 =item setpwent
 
-Not implemented. (MPE/iX, Win32)
+Not implemented. (S<Mac OS>, MPE/iX, Win32, S<RISC OS>)
 
 =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
 
@@ -1834,8 +1873,8 @@ C<$?> right by eight to get the exit value, or that C<$? & 127>
 would give you the number of the signal that terminated the program,
 or that C<$? & 128> would test true if the program was terminated by a
 coredump.  Instead, use the POSIX W*() interfaces: for example, use
-WIFEXITED($?) an WEXITVALUE($?) to test for a normal exit and the exit
-value, and WIFSIGNALED($?) and WTERMSIG($?)  for a signal exit and the
+WIFEXITED($?) and WEXITVALUE($?) to test for a normal exit and the exit
+value, WIFSIGNALED($?) and WTERMSIG($?) for a signal exit and the
 signal.  Core dumping is not a portable concept, so there's no portable
 way to test for that.
 
@@ -2030,7 +2069,7 @@ distribution available at http://www.cpan.org/src/index.html
        DG/UX
        DOS DJGPP       1)
        DYNIX/ptx
-       EPOC
+       EPOC R5
        FreeBSD
        HP-UX
        IRIX
@@ -2148,7 +2187,7 @@ Support for the following platform is planned for a future Perl release:
        Netware
 
 The following platforms have their own source code distributions and
-binaries available via http://www.cpan.org/ports/index.html:
+binaries available via http://www.cpan.org/ports/
 
                                Perl release