clarify docs on return value from binding operators
[p5sagit/p5-mst-13.2.git] / pod / perlport.pod
index 5c0c71c..10723ee 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
-(E<lt>IMG SRC="yellow_sign.gif" ALT="Under Construction"E<gt>).
+(<IMG SRC="yellow_sign.gif" ALT="Under Construction">).
 
 =head1 ISSUES
 
@@ -90,7 +90,7 @@ Perl uses C<\n> to represent the "logical" newline, where what is
 logical may depend on the platform in use.  In MacPerl, C<\n> always
 means C<\015>.  In DOSish perls, C<\n> usually means C<\012>, but
 when accessing a file in "text" mode, STDIO translates it to (or
-from) C<\015\012>, depending on whether your reading or writing.
+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.
 
@@ -303,15 +303,15 @@ first 8 characters.
 Whitespace in filenames is tolerated on most systems, but not all.
 Many systems (DOS, VMS) cannot have more than one C<.> in their filenames.
 
-Don't assume C<E<gt>> won't be the first character of a filename.
-Always use C<E<lt>> explicitly to open a file for reading,
+Don't assume C<< > >> won't be the first character of a filename.
+Always use C<< < >> explicitly to open a file for reading,
 unless you want the user to be able to specify a pipe open.
 
     open(FILE, "< $existing_file") or die $!;
 
 If filenames might use strange characters, it is safest to open it
 with C<sysopen> instead of C<open>.  C<open> is magic and can
-translate characters like C<E<gt>>, C<E<lt>>, and C<|>, which may
+translate characters like C<< > >>, C<< < >>, and C<|>, which may
 be the wrong thing to do.  (Sometimes, though, it's the right thing.)
 
 =head2 System Interaction
@@ -528,7 +528,7 @@ a given module works on a given platform.
 
 =item Mailing list: cpan-testers@perl.org
 
-=item Testing results: C<http://www.perl.org/cpan-testers/>
+=item Testing results: C<http://testers.cpan.org/>
 
 =back
 
@@ -648,6 +648,7 @@ DOSish perls are as follows:
     Windows NT    MSWin32    MSWin32-x86
     Windows NT    MSWin32    MSWin32-ALPHA
     Windows NT    MSWin32    MSWin32-ppc
+    Cygwin        cygwin
 
 Also see:
 
@@ -663,8 +664,8 @@ C<ftp://hobbes.nmsu.edu/pub/os2/dev/emx>
 
 =item The ActiveState Pages, C<http://www.activestate.com/>
 
-=item The Cygwin32 environment for Win32; L<README.cygwin32>,
-C<http://www.cygnus.com/misc/gnu-win32/>
+=item The Cygwin environment for Win32; F<README.cygwin> (installed 
+as L<perlcygwin>), C<http://sourceware.cygnus.com/cygwin/>
 
 =item The U/WIN environment for Win32,
 C<http://www.research.att.com/sw/tools/uwin/>
@@ -786,7 +787,7 @@ you are so inclined.  For example:
     $ endif
 
 Do take care with C<$ ASSIGN/nolog/user SYS$COMMAND: SYS$INPUT> if your
-perl-in-DCL script expects to do things like C<$read = E<lt>STDINE<gt>;>.
+perl-in-DCL script expects to do things like C<< $read = <STDIN>; >>.
 
 Filenames are in the format "name.extension;version".  The maximum
 length for filenames is 39 characters, and the maximum length for
@@ -843,7 +844,7 @@ Also see:
 
 =over 4
 
-=item L<README.vms>, L<perlvms.pod>
+=item F<README.vms> (installed as L<README_vms>), L<perlvms>
 
 =item vmsperl list, C<majordomo@perl.org>
 
@@ -870,7 +871,8 @@ Even though VOS allows the slash character to appear in object
 names, because the VOS port of Perl interprets it as a pathname
 delimiting character, VOS files, directories, or links whose names
 contain a slash character cannot be processed.  Such files must be
-renamed before they can be processed by Perl.
+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
@@ -883,7 +885,7 @@ 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:
 
-    if (grep(/VOS/, @INC)) {
+    if ($^O =~ /VOS/) {
         print "I'm on a Stratus box!\n";
     } else {
         print "I'm not on a Stratus box!\n";
@@ -894,20 +896,20 @@ can examine the content of the C<@INC> array like so:
         print "This box is a Stratus XA/R!\n";
 
     } elsif (grep(/7100/, @INC)) {
-        print "This box is a Stratus HP 7100 or 8000!\n";
+        print "This box is a Stratus HP 7100 or 8xxx!\n";
 
     } elsif (grep(/8000/, @INC)) {
-        print "This box is a Stratus HP 8000!\n";
+        print "This box is a Stratus HP 8xxx!\n";
 
     } else {
-        print "This box is a Stratus 68K...\n";
+        print "This box is a Stratus 68K!\n";
     }
 
 Also see:
 
 =over 4
 
-=item L<README.vos>
+=item F<README.vos>
 
 =item VOS mailing list
 
@@ -925,10 +927,10 @@ the message body to majordomo@list.stratagy.com.
 Recent versions of Perl have been ported to platforms such as OS/400 on
 AS/400 minicomputers as well as OS/390, VM/ESA, and BS2000 for S/390
 Mainframes.  Such computers use EBCDIC character sets internally (usually
-Character Code Set ID 00819 for OS/400 and 1047 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 system (BS2000 is supported in perl 5.006 and greater).
+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).
 
 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.
@@ -997,7 +999,7 @@ Also see:
 
 =over 4
 
-=item L<README.os390>, L<README.posix-bc>, L<README.vmesa>
+=item F<README.os390>, F<README.posix-bc>, F<README.vmesa>
 
 =item perl-mvs list
 
@@ -1051,9 +1053,9 @@ C<System$Path> until a name is made that points to an object on disk.
 Writing to a new file C<System:Modules> would be allowed only if
 C<System$Path> contains a single item list.  The filesystem will also
 expand system variables in filenames if enclosed in angle brackets, so
-C<E<lt>System$DirE<gt>.Modules> would look for the file
+C<< <System$Dir>.Modules >> would look for the file
 S<C<$ENV{'System$Dir'} . 'Modules'>>.  The obvious implication of this is
-that B<fully qualified filenames can start with C<E<lt>E<gt>>> and should
+that B<fully qualified filenames can start with C<< <> >>> and should
 be protected when C<open> is used for input.
 
 Because C<.> was in use as a directory separator and filenames could not
@@ -1093,11 +1095,11 @@ library emulates Unix filehandles.  Consequently, you can't rely on
 passing C<STDIN>, C<STDOUT>, or C<STDERR> to your children.
 
 The desire of users to express filenames of the form
-C<E<lt>Foo$DirE<gt>.Bar> on the command line unquoted causes problems,
+C<< <Foo$Dir>.Bar >> on the command line unquoted causes problems,
 too: C<``> command output capture has to perform a guessing game.  It
-assumes that a string C<E<lt>[^E<lt>E<gt>]+\$[^E<lt>E<gt>]E<gt>> is a
+assumes that a string C<< <[^<>]+\$[^<>]> >> is a
 reference to an environment variable, whereas anything else involving
-C<E<lt>> or C<E<gt>> is redirection, and generally manages to be 99%
+C<< < >> or C<< > >> is redirection, and generally manages to be 99%
 right.  Of course, the problem remains that scripts cannot rely on any
 Unix tools being available, or that any tools found have Unix-like command
 line arguments.
@@ -1136,14 +1138,14 @@ See also:
 
 =over 4
 
-=item Amiga, L<README.amiga>
+=item Amiga, F<README.amiga> (installed as L<perlamiga>).
 
-=item Atari, L<README.mint> and Guido Flohr's web page
+=item Atari, F<README.mint> and Guido Flohr's web page
 C<http://stud.uni-sb.de/~gufl0000/>
 
-=item Be OS, L<README.beos>
+=item Be OS, F<README.beos>
 
-=item HP 300 MPE/iX, L<README.mpeix> and Mark Bixby's web page
+=item HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page
 C<http://www.cccd.edu/~markb/perlix.html>
 
 =item Novell Netware
@@ -1152,7 +1154,7 @@ A free perl5-based PERL.NLM for Novell Netware is available in
 precompiled binary and source code form from C<http://www.novell.com/>
 as well as from CPAN.
 
-=item Plan 9, L<README.plan9>
+=item Plan 9, F<README.plan9>
 
 =back
 
@@ -1401,11 +1403,11 @@ Not implemented. (Plan9, Win32, S<RISC OS>)
 
 =item endpwent
 
-Not implemented. (S<Mac OS>, Win32, VM/ESA)
+Not implemented. (S<Mac OS>, MPE/iX, VM/ESA, Win32)
 
 =item endgrent
 
-Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VM/ESA)
+Not implemented. (S<Mac OS>, MPE/iX, S<RISC OS>, VM/ESA, VMS, Win32)
 
 =item endhostent
 
@@ -1452,21 +1454,25 @@ in the Winsock API does. (Win32)
 
 Available only for socket handles. (S<RISC OS>)
 
-=item kill LIST
+=item kill SIGNAL, LIST
 
 Not implemented, hence not useful for taint checking. (S<Mac OS>,
 S<RISC OS>)
 
-Available only for process handles returned by the C<system(1, ...)>
-method of spawning a process. (Win32)
+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)
 
 =item link OLDFILE,NEWFILE
 
-Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>)
+Not implemented. (S<Mac OS>, MPE/iX, VMS, S<RISC OS>)
 
 Link count not updated because hard links are not quite that hard
 (They are sort of half-way between hard and soft links). (AmigaOS)
 
+Hard links are implemented on Win32 (Windows NT and Windows 2000)
+under NTFS only.
+
 =item lstat FILEHANDLE
 
 =item lstat EXPR
@@ -1522,6 +1528,10 @@ Only reliable on sockets. (S<RISC OS>)
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
+=item setgrent
+
+Not implemented. (MPE/iX, Win32)
+
 =item setpgrp PID,PGRP
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
@@ -1530,6 +1540,10 @@ Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
 Not implemented. (S<Mac OS>, Win32, VMS, S<RISC OS>, VOS)
 
+=item setpwent
+
+Not implemented. (MPE/iX, Win32)
+
 =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
 
 Not implemented. (S<Mac OS>, Plan9)
@@ -1591,7 +1605,7 @@ in C<wait> or C<waitpid>.  (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<E<gt> foo> is performed (if at all) by
+program.  Redirection such as C<< > foo >> is performed (if at all) by
 the run time library of the spawned program.  C<system> I<list> will call
 the Unix emulation library's C<exec> emulation, which attempts to provide
 emulation of the stdin, stdout, stderr in force in the parent, providing
@@ -1602,7 +1616,7 @@ of a child Unix program will exists.  Mileage B<will> vary.  (S<RISC OS>)
 Far from being POSIX compliant.  Because there may be no underlying
 /bin/sh tries to work around the problem by forking and execing the
 first token in its argument string.  Handles basic redirection
-("E<lt>" or "E<gt>") on its own behalf. (MiNT)
+("<" or ">") on its own behalf. (MiNT)
 
 =item times
 
@@ -1663,6 +1677,14 @@ Not useful. (S<RISC OS>)
 
 =over 4
 
+=item v1.46, 12 February 2000
+
+Updates for VOS and MPE/iX. (Peter Prymmer)  Other small changes.
+
+=item v1.45, 20 December 1999
+
+Small changes from 5.005_63 distribution, more changes to EBCDIC info.
+
 =item v1.44, 19 July 1999
 
 A bunch of updates from Peter Prymmer for C<$^O> values,
@@ -1732,41 +1754,42 @@ First public release with perl5.005.
 
 =head1 AUTHORS / CONTRIBUTORS
 
-Abigail E<lt>abigail@fnx.comE<gt>,
-Charles Bailey E<lt>bailey@newman.upenn.eduE<gt>,
-Graham Barr E<lt>gbarr@pobox.comE<gt>,
-Tom Christiansen E<lt>tchrist@perl.comE<gt>,
-Nicholas Clark E<lt>Nicholas.Clark@liverpool.ac.ukE<gt>,
-Thomas Dorner E<lt>Thomas.Dorner@start.deE<gt>,
-Andy Dougherty E<lt>doughera@lafcol.lafayette.eduE<gt>,
-Dominic Dunlop E<lt>domo@vo.luE<gt>,
-Neale Ferguson E<lt>neale@mailbox.tabnsw.com.auE<gt>,
-David J. Fiander E<lt>davidf@mks.comE<gt>,
-Paul Green E<lt>Paul_Green@stratus.comE<gt>,
-M.J.T. Guy E<lt>mjtg@cus.cam.ac.ukE<gt>,
-Jarkko Hietaniemi E<lt>jhi@iki.fi<gt>,
-Luther Huffman E<lt>lutherh@stratcom.comE<gt>,
-Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>,
-Andreas J. KE<ouml>nig E<lt>koenig@kulturbox.deE<gt>,
-Markus Laker E<lt>mlaker@contax.co.ukE<gt>,
-Andrew M. Langmead E<lt>aml@world.std.comE<gt>,
-Larry Moore E<lt>ljmoore@freespace.netE<gt>,
-Paul Moore E<lt>Paul.Moore@uk.origin-it.comE<gt>,
-Chris Nandor E<lt>pudge@pobox.comE<gt>,
-Matthias Neeracher E<lt>neeri@iis.ee.ethz.chE<gt>,
-Gary Ng E<lt>71564.1743@CompuServe.COME<gt>,
-Tom Phoenix E<lt>rootbeer@teleport.comE<gt>,
-Peter Prymmer E<lt>pvhp@forte.comE<gt>,
-Hugo van der Sanden E<lt>hv@crypt0.demon.co.ukE<gt>,
-Gurusamy Sarathy E<lt>gsar@umich.eduE<gt>,
-Paul J. Schinder E<lt>schinder@pobox.comE<gt>,
-Michael G Schwern E<lt>schwern@pobox.comE<gt>,
-Dan Sugalski E<lt>sugalskd@ous.eduE<gt>,
-Nathan Torkington E<lt>gnat@frii.comE<gt>.
+Abigail <abigail@fnx.com>,
+Charles Bailey <bailey@newman.upenn.edu>,
+Graham Barr <gbarr@pobox.com>,
+Tom Christiansen <tchrist@perl.com>,
+Nicholas Clark <Nicholas.Clark@liverpool.ac.uk>,
+Thomas Dorner <Thomas.Dorner@start.de>,
+Andy Dougherty <doughera@lafcol.lafayette.edu>,
+Dominic Dunlop <domo@vo.lu>,
+Neale Ferguson <neale@mailbox.tabnsw.com.au>,
+David J. Fiander <davidf@mks.com>,
+Paul Green <Paul_Green@stratus.com>,
+M.J.T. Guy <mjtg@cus.cam.ac.uk>,
+Jarkko Hietaniemi <jhi@iki.fi<gt>,
+Luther Huffman <lutherh@stratcom.com>,
+Nick Ing-Simmons <nick@ni-s.u-net.com>,
+Andreas J. KE<ouml>nig <koenig@kulturbox.de>,
+Markus Laker <mlaker@contax.co.uk>,
+Andrew M. Langmead <aml@world.std.com>,
+Larry Moore <ljmoore@freespace.net>,
+Paul Moore <Paul.Moore@uk.origin-it.com>,
+Chris Nandor <pudge@pobox.com>,
+Matthias Neeracher <neeri@iis.ee.ethz.ch>,
+Gary Ng <71564.1743@CompuServe.COM>,
+Tom Phoenix <rootbeer@teleport.com>,
+AndrE<eacute> Pirard <A.Pirard@ulg.ac.be>,
+Peter Prymmer <pvhp@forte.com>,
+Hugo van der Sanden <hv@crypt0.demon.co.uk>,
+Gurusamy Sarathy <gsar@activestate.com>,
+Paul J. Schinder <schinder@pobox.com>,
+Michael G Schwern <schwern@pobox.com>,
+Dan Sugalski <sugalskd@ous.edu>,
+Nathan Torkington <gnat@frii.com>.
 
 This document is maintained by Chris Nandor
-E<lt>pudge@pobox.comE<gt>.
+<pudge@pobox.com>.
 
 =head1 VERSION
 
-Version 1.44, last modified 22 July 1999
+Version 1.46, last modified 12 February 2000