trivial docu patch

[p5sagit/p5-mst-13.2.git] / pod / perlport.pod

diff --git a/pod/perlport.pod b/pod/perlport.pod
index 8d4e569..9b81ca5 100644 (file)
--- a/pod/perlport.pod
+++ b/pod/perlport.pod
@@ -267,6 +267,13 @@ S<RISC OS> perl can emulate Unix filenames with C</> as path
 separator, or go native and use C<.> for path separator and C<:> to
 signal filesystems and disk names.
 
+Don't assume UNIX filesystem access semantics: that read, write,
+and execute are all the permissions there are, and even if they exist,
+that their semantics (for example what do r, w, and x mean on
+a directory) are the UNIX ones.  The various UNIX/POSIX compatibility
+layers usually try to make interfaces like chmod() work, but sometimes
+there simply is no good mapping.
+
 If all this is intimidating, have no (well, maybe only a little)
 fear.  There are modules that can help.  The File::Spec modules
 provide methods to do the Right Thing on whatever platform happens
@@ -538,13 +545,31 @@ more efficient that the first.
 
 Most multi-user platforms provide basic levels of security, usually
 implemented at the filesystem level.  Some, however, do
-not--unfortunately.  Thus the notion of user id, or "home" directory,
+not-- unfortunately.  Thus the notion of user id, or "home" directory,
 or even the state of being logged-in, may be unrecognizable on many
 platforms.  If you write programs that are security-conscious, it
 is usually best to know what type of system you will be running
 under so that you can write code explicitly for that platform (or
 class of platforms).
 
+Don't assume the UNIX filesystem access semantics: the operating
+system or the filesystem may be using some ACL systems, which are
+richer languages than the usual rwx.  Even if the rwx exist,
+their semantics might be different.
+
+(From security viewpoint testing for permissions before attempting to
+do something is silly anyway: if one tries this, there is potential
+for race conditions-- someone or something might change the
+permissions between the permissions check and the actual operation.
+Just try the operation.)
+
+Don't assume the UNIX user and group semantics: especially, don't
+expect the C<< $< >> and C<< $> >> (or the C<$(> and C<$)>) to work
+for switching identities (or memberships).
+
+Don't assume set-uid and set-gid semantics. (And even if you do,
+think twice: set-uid and set-gid are a known can of security worms.)
+
 =head2 Style
 
 For those times when it is necessary to have platform-specific code,
@@ -1658,7 +1683,7 @@ Not implemented. (Win32, VMS, S<RISC OS>)
 
 =item select RBITS,WBITS,EBITS,TIMEOUT
 
-Only implemented on sockets. (Win32)
+Only implemented on sockets. (Win32, VMS)
 
 Only reliable on sockets. (S<RISC OS>)
 
@@ -1754,6 +1779,16 @@ OS>, OS/390, VM/ESA)
 
 =item system LIST
 
+In general, do not assume the UNIX/POSIX semantics that you can shift
+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
+signal.  Core dumping is not a portable concept, so there's no portable
+way to test for that.
+
 Only implemented if ToolServer is installed. (S<Mac OS>)
 
 As an optimization, may not call the command shell specified in
@@ -1823,7 +1858,7 @@ is finally closed. (AmigaOS)
 
 =item utime LIST
 
-Only the modification time is updated. (S<Mac OS>, VMS, S<RISC OS>)
+Only the modification time is updated. (S<BeOS>, S<Mac OS>, VMS, S<RISC OS>)
 
 May not behave as expected.  Behavior depends on the C runtime
 library's implementation of utime(), and the filesystem being