This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
socketpair() *is* available on Win32
[perl5.git] / pod / perlport.pod
index 3458c7c..c6c7891 100644 (file)
@@ -94,21 +94,9 @@ 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(<FILE>) {
-        chop;
-        @array = split(/:/);
-        #...
-    }
-
-You can get away with this on Unix and Mac OS (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 L<Dunce::Files> module 
-can help audit your code for misuses of chop().
+To trim trailing newlines from text lines use chomp().  With default 
+settings that function looks for a trailing C<\n> character and thus 
+trims in a portable way.
 
 When dealing with binary files (or text files in binary mode) be sure
 to explicitly set $/ to the appropriate value for your file format
@@ -445,6 +433,16 @@ 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.
 
+On VMS, some entries in the %ENV hash are dynamically created when
+their key is used on a read if they did not previously exist.  The
+values for C<$ENV{HOME}>, C<$ENV{TERM}>, C<$ENV{HOME}>, and C<$ENV{USER}>,
+are known to be dynamically generated.  The specific names that are
+dynamically generated may vary with the version of the C library on VMS,
+and more may exist than is documented.
+
+On VMS by default, changes to the %ENV hash are persistent after the process
+exits.  This can cause unintended issues.
+
 Don't count on signals or C<%SIG> for anything.
 
 Don't count on filename globbing.  Use C<opendir>, C<readdir>, and
@@ -684,12 +682,9 @@ ISO 8859-1 bytes beyond 0x7f into your strings might cause trouble
 later.  If the bytes are native 8-bit bytes, you can use the C<bytes>
 pragma.  If the bytes are in a string (regular expression being a
 curious string), you can often also use the C<\xHH> notation instead
-of embedding the bytes as-is.  If they are in some particular legacy
-encoding (ether single-byte or something more complicated), you can
-use the C<encoding> pragma.  (If you want to write your code in UTF-8,
-you can use either the C<utf8> pragma, or the C<encoding> pragma.)
-The C<bytes> and C<utf8> pragmata are available since Perl 5.6.0, and
-the C<encoding> pragma since Perl 5.8.0.
+of embedding the bytes as-is.  (If you want to write your code in UTF-8,
+you can use the C<utf8>.) The C<bytes> and C<utf8> pragmata are
+available since Perl 5.6.0.
 
 =head2 System Resources
 
@@ -1171,11 +1166,18 @@ a VMS format directory, then C<readdir> should return F<a.>, and
 again with the optionally the exact case.
 
 RMS had an eight level limit on directory depths from any rooted logical
-(allowing 16 levels overall) prior to VMS 7.2.  Hence
-C<PERL_ROOT:[LIB.2.3.4.5.6.7.8]> is a valid directory specification but
-C<PERL_ROOT:[LIB.2.3.4.5.6.7.8.9]> is not.  F<Makefile.PL> authors might
-have to take this into account, but at least they can refer to the former
-as C</PERL_ROOT/lib/2/3/4/5/6/7/8/>.
+(allowing 16 levels overall) prior to VMS 7.2, and even with versions of
+VMS on VAX up through 7.3.  Hence C<PERL_ROOT:[LIB.2.3.4.5.6.7.8]> is a
+valid directory specification but C<PERL_ROOT:[LIB.2.3.4.5.6.7.8.9]> is
+not.  F<Makefile.PL> authors might have to take this into account, but at
+least they can refer to the former as C</PERL_ROOT/lib/2/3/4/5/6/7/8/>.
+
+Pumpkings and module integrators can easily see whether files with too many
+directory levels have snuck into the core by running the following in the
+top-level source directory:
+
+   $ perl -ne "$_=~s/\s+.*//; print if scalar(split /\//) > 8;" < MANIFEST
+
 
 The VMS::Filespec module, which gets installed as part of the build
 process on VMS, is a pure Perl module that can easily be installed on
@@ -1231,9 +1233,7 @@ F<README.vms> (installed as L<README_vms>), L<perlvms>
 
 =item *
 
-vmsperl list, majordomo@perl.org
-
-(Put the words C<subscribe vmsperl> in message body.)
+vmsperl list, vmsperl-subscribe@perl.org
 
 =item *
 
@@ -1678,7 +1678,7 @@ Not implemented. (VMS, S<Plan 9>, VOS)
 
 Not useful. (S<Mac OS>, S<RISC OS>)
 
-Not implemented. (Win32)
+Not supported. (Cygwin, Win32)
 
 Invokes VMS debugger. (VMS)
 
@@ -1882,6 +1882,12 @@ 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)
 
+C<kill(-9, $pid)> will terminate the process specified by $pid and
+recursively all child processes owned by it.  This is different from
+the Unix semantics, where the signal will be delivered to all
+processes in the same process group as the process specified by
+$pid. (Win32)
+
 Is not supported for process identification number of 0 or negative
 numbers. (VMS)
 
@@ -1892,8 +1898,11 @@ Not implemented. (S<Mac OS>, MPE/iX, 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.
+Hard links are implemented on Win32 under NTFS only. They are
+natively supported on Windows 2000 and later.  On Windows NT they
+are implemented using the Windows POSIX subsystem support and the
+Perl process will need Administrator or Backup Operator privileges
+to create hard links.
 
 Available on 64 bit OpenVMS 8.2 and later.  (VMS)
 
@@ -1995,7 +2004,7 @@ be implemented even in UNIX platforms.
 
 =item socketpair
 
-Not implemented. (Win32, S<RISC OS>, VOS, VM/ESA)
+Not implemented. (S<RISC OS>, VOS, VM/ESA)
 
 Available on 64 bit OpenVMS 8.2 and later.  (VMS)
 
@@ -2025,9 +2034,17 @@ meaningful and will differ between stat calls on the same file.  (os2)
 some versions of cygwin when doing a stat("foo") and if not finding it
 may then attempt to stat("foo.exe") (Cygwin)
 
+On Win32 stat() needs to open the file to determine the link count
+and update attributes that may have been changed through hard links.
+Setting ${^WIN32_SLOPPY_STAT} to a true value speeds up stat() by
+not performing this operation. (Win32)
+
 =item symlink
 
-Not implemented. (Win32, VMS, S<RISC OS>)
+Not implemented. (Win32, S<RISC OS>)
+
+Implemented on 64 bit VMS 8.3.  VMS requires the symbolic link to be in Unix
+syntax if it is intended to resolve to a valid path.
 
 =item syscall