Integrate mainline. Builds lots of sv.h/embed.h redef warnings

[perl5.git] / pod / perlport.pod

diff --git a/pod/perlport.pod b/pod/perlport.pod
index 1414b26..8e94e22 100644 (file)
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -352,6 +352,25 @@ file already tied or opened; C<untie> or C<close> 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<unlink> 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.  Don't try to clear %ENV by saying C<%ENV = ();>, or,
@@ -404,6 +423,14 @@ simple, platform-independent mailing.
 The Unix System V IPC (C<msg*(), sem*(), shm*()>) is not available
 even on all Unix platforms.
 
+Do not use either the bare result of C<pack("N", 10, 20, 30, 40)>
+or bare v-strings (such as C<v10.20.30.40>) or to represent
+IPv4 addresses: both forms just pack the four bytes into network order.
+That this would be equal to the C language C<in_addr> 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<inet_aton()>, C<inet_ntoa()>, and C<sockaddr_in()>.
+
 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).
@@ -663,17 +690,22 @@ 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 
@@ -1540,7 +1572,7 @@ is used directly as Perl's exit status. (VMS)
 
 =item getsockopt SOCKET,LEVEL,OPTNAME
 
-Not implemented. (S<Mac OS>, Plan9)
+Not implemented. (Plan9)
 
 =item glob EXPR
 
@@ -1658,7 +1690,7 @@ Not implemented. (MPE/iX, Win32)
 
 =item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
 
-Not implemented. (S<Mac OS>, Plan9)
+Not implemented. (Plan9)
 
 =item shmctl ID,CMD,ARG
 
@@ -1702,6 +1734,9 @@ inode are not necessarily reliable.  (S<RISC OS>)
 dev, rdev, blksize, and blocks are not available.  inode is not
 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)
+
 =item symlink OLDFILE,NEWFILE
 
 Not implemented. (Win32, VMS, S<RISC OS>)