Fcntl: more O_ constants, move SEEK_ to @EXPORT_OK

(tag :seek), add S_I constants (and functions) (tag :mode);
refer only to the SEEK_ of Fcntl, not the ones from
POSIX or IO::; add SHUT_ to Socket; get trigonometric
functions from Math::Trig instead of POSIX.

p4raw-id: //depot/cfgperl@5118

3 files changed, 89 insertions, 16 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 46dd6564e4..4761ef03e9 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -1397,8 +1397,11 @@ large file (more than 4GB) access Note that the O_LARGEFILE is
 automatically/transparently added to sysopen() flags if large file
 support has been configured), Free/Net/OpenBSD locking behaviour flags
 F_FLOCK, F_POSIX, Linux F_SHLCK, and O_ACCMODE: the combined mask of
-O_RDONLY, O_WRONLY, and O_RDWR.  Also SEEK_SET, SEEK_CUR, and SEEK_END
-added for one-stop shopping of the seek/sysseek constants.
+O_RDONLY, O_WRONLY, and O_RDWR.  The seek()/sysseek() constants
+SEEK_SET, SEEK_CUR, and SEEK_END are available via the C<:seek> tag.
+The chmod()/stat() S_IF* constants and S_IS* functions are available
+via the C<:mode> tag.
+
 
 =item File::Compare
 
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index e8f4fe0880..3d037438ab 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -423,7 +423,7 @@ modulo the caveats given in L<perlipc/"Signals">.
 
 Returns the arctangent of Y/X in the range -PI to PI.
 
-For the tangent operation, you may use the C<POSIX::tan()>
+For the tangent operation, you may use the C<Math::Trig::tan>
 function, or use the familiar relation:
 
     sub tan { sin($_[0]) / cos($_[0])  }
@@ -559,6 +559,14 @@ successfully changed.  See also L</oct>, if all you have is a string.
     $mode = '0644'; chmod oct($mode), 'foo'; # this is better
     $mode = 0644;   chmod $mode, 'foo';      # this is best
 
+You can also import the symbolic C<S_I*> constants from the Fcntl
+module:
+
+    use Fcntl ':mode';
+
+    chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
+    # This is identical to the chmod 0755 of the above example.
+
 =item chomp VARIABLE
 
 =item chomp LIST
@@ -766,7 +774,7 @@ to check the condition at the top of the loop.
 Returns the cosine of EXPR (expressed in radians).  If EXPR is omitted,
 takes cosine of C<$_>.
 
-For the inverse cosine operation, you may use the C<POSIX::acos()>
+For the inverse cosine operation, you may use the C<Math::Trig::acos()>
 function, or use this relation:
 
     sub acos { atan2( sqrt(1 - $_[0] * $_[0]), $_[0] ) }
@@ -2319,7 +2327,7 @@ This scalar value is B<not> locale dependent, see L<perllocale>, but
 instead a Perl builtin.  Also see the C<Time::Local> module
 (to convert the second, minutes, hours, ... back to seconds since the
 stroke of midnight the 1st of January 1970, the value returned by
-time()), and the strftime(3) and mktime(3) function available via the
+time()), and the strftime(3) and mktime(3) functions available via the
 POSIX module.  To get somewhat similar but locale dependent date
 strings, set up your locale environment variables appropriately
 (please see L<perllocale>) and try for example:
@@ -3719,9 +3727,8 @@ filehandle.  The values for WHENCE are C<0> to set the new position to
 POSITION, C<1> to set it to the current position plus POSITION, and
 C<2> to set it to EOF plus POSITION (typically negative).  For WHENCE
 you may use the constants C<SEEK_SET>, C<SEEK_CUR>, and C<SEEK_END>
-(start of the file, current position, end of the file) from any of the
-modules Fcntl, C<IO::Seekable>, or POSIX.  Returns C<1> upon success,
-C<0> otherwise.
+(start of the file, current position, end of the file) from the Fcntl
+module.  Returns C<1> upon success, C<0> otherwise.
 
 If you want to position file for C<sysread> or C<syswrite>, don't use
 C<seek>--buffering makes its effect on the file's system position
@@ -3970,7 +3977,7 @@ processes.
 Returns the sine of EXPR (expressed in radians).  If EXPR is omitted,
 returns sine of C<$_>.
 
-For the inverse sine operation, you may use the C<POSIX::asin>
+For the inverse sine operation, you may use the C<Math::Trig::asin>
 function, or use this relation:
 
     sub asin { atan2($_[0], sqrt(1 - $_[0] * $_[0])) }
@@ -4491,7 +4498,8 @@ last stat or filetest are returned.  Example:
 	print "$file is executable NFS file\n";
     }
 
-(This works on machines only for which the device number is negative under NFS.)
+(This works on machines only for which the device number is negative
+under NFS.)
 
 Because the mode contains both the file type and its permissions, you
 should mask off the file type portion and (s)printf using a C<"%o"> 
@@ -4512,6 +4520,66 @@ The File::stat module provides a convenient, by-name access mechanism:
 	$filename, $sb->size, $sb->mode & 07777,
 	scalar localtime $sb->mtime;
 
+You can import symbolic mode constants (C<S_IF*>) and functions
+(C<S_IS*>) from the Fcntl module:
+
+    use Fcntl ':mode';
+
+    $mode = (stat($filename))[2];
+
+    $user_rwx      = ($mode & S_IRWXU) >> 6;
+    $group_read    = ($mode & S_IRGRP) >> 3;
+    $other_execute =  $mode & S_IXOTH;
+
+    printf "Permissions are %04o\n", S_ISMODE($mode), "\n";
+
+    $is_setuid     =  $mode & S_ISUID;
+    $is_setgid     =  S_ISDIR($mode);
+
+You could write the last two using the C<-u> and C<-d> operators.
+The commonly available S_IF* constants are
+
+    # Permissions: read, write, execute, for user, group, others.
+
+    S_IRWXU S_IRUSR S_IWUSR S_IXUSR
+    S_IRWXG S_IRGRP S_IWGRP S_IXGRP
+    S_IRWXO S_IROTH S_IWOTH S_IXOTH
+    
+    # Setuid/Setgid/Stickiness.
+
+    S_ISUID S_ISGID S_ISVTX S_ISTXT
+
+    # File types.  Not necessarily all are available on your system.
+
+    S_IFREG S_IFDIR S_IFLNK S_IFBLK S_ISCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
+
+    # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
+
+    S_IREAD S_IWRITE S_IEXEC
+
+and the S_IF* functions are
+
+    S_IFMODE($mode)	the part of $mode containg the permission bits
+			and the setuid/setgid/sticky bits
+
+    S_IFMT($mode)	the part of $mode containing the file type
+			which can be bit-anded with e.g. S_IFREG 
+                        or with the following functions
+
+    # The operators -f, -d, -l, -b, -c, -p, and -s.
+
+    S_ISREG($mode) S_ISDIR($mode) S_ISLNK($mode)
+    S_ISBLK($mode) S_ISCHR($mode) S_ISFIFO($mode) S_ISSOCK($mode)
+
+    # No direct -X operator counterpart, but for the first one
+    # the -g operator is often equivalent.  The ENFMT stands for
+    # record flocking enforcement, a platform-dependent feature.
+
+    S_ISENFMT($mode) S_ISWHT($mode)
+
+See your native chmod(2) and stat(2) documentation for more details
+about the S_* constants.
+
 =item study SCALAR
 
 =item study
@@ -4751,7 +4819,7 @@ POSITION, C<1> to set the it to the current position plus POSITION,
 and C<2> to set it to EOF plus POSITION (typically negative).  For
 WHENCE, you may also use the constants C<SEEK_SET>, C<SEEK_CUR>, and
 C<SEEK_END> (start of the file, current position, end of the file)
-from any of the modules Fcntl, C<IO::Seekable>, or POSIX.
+from the Fcntl module.
 
 Returns the new position, or the undefined value on failure.  A position
 of zero is returned as the string C<"0 but true">; thus C<sysseek> returns
diff --git a/pod/perlopentut.pod b/pod/perlopentut.pod
index fd32bd9f49..cc9cf63ff2 100644
--- a/pod/perlopentut.pod
+++ b/pod/perlopentut.pod
@@ -303,11 +303,13 @@ from the Fcntl module, which supplies the following standard flags:
     O_TRUNC             Truncate the file
     O_NONBLOCK          Non-blocking access
 
-Less common flags that are sometimes available on some operating systems
-include C<O_BINARY>, C<O_TEXT>, C<O_SHLOCK>, C<O_EXLOCK>, C<O_DEFER>,
-C<O_SYNC>, C<O_ASYNC>, C<O_DSYNC>, C<O_RSYNC>, C<O_NOCTTY>, C<O_NDELAY>
-and C<O_LARGEFILE>.  Consult your open(2) manpage or its local equivalent
-for details.
+Less common flags that are sometimes available on some operating
+systems include C<O_BINARY>, C<O_TEXT>, C<O_SHLOCK>, C<O_EXLOCK>,
+C<O_DEFER>, C<O_SYNC>, C<O_ASYNC>, C<O_DSYNC>, C<O_RSYNC>,
+C<O_NOCTTY>, C<O_NDELAY> and C<O_LARGEFILE>.  Consult your open(2)
+manpage or its local equivalent for details.  (Note: starting from
+Perl release 5.6 the O_LARGEFILE flag, if available, is automatically
+added to the sysopen() flags because large files are the the default.)
 
 Here's how to use C<sysopen> to emulate the simple C<open> calls we had
 before.  We'll omit the C<|| die $!> checks for clarity, but make sure