From: Ben Morrow <ben@morrow.me.uk>
Date: Tue, 20 Jan 2009 09:15:46 +0000 (+0000)
Subject: Docs for File::stat.
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6cf0ee866a04e630cd1706bc6ff2e05de936ba2b;p=p5sagit%2Fp5-mst-13.2.git

Docs for File::stat.
---

diff --git a/lib/File/stat.pm b/lib/File/stat.pm
index 282f7c9..630fae1 100644
--- a/lib/File/stat.pm
+++ b/lib/File/stat.pm
@@ -221,6 +221,15 @@ File::stat - by-name interface to Perl's built-in stat() functions
      print "$file is executable with lotsa links\n";
  } 
 
+ if ( -x $st ) {
+     print "$file is executable\n";
+ }
+
+ use Fcntl "S_IRUSR";
+ if ( $st->cando(S_IRUSR, 1) ) {
+     print "My effective uid can read $file\n";
+ }
+
  use File::stat qw(:FIELDS);
  stat($file) or die "No $file: $!";
  if ( ($st_mode & 0111) && ($st_nlink > 1) ) {
@@ -249,6 +258,23 @@ blksize,
 and
 blocks.  
 
+As of version 1.02 (provided with perl 5.12) the object provides C<"-X">
+overloading, so you can call filetest operators (C<-f>, C<-x>, and so
+on) on it. It also provides a C<< ->cando >> method, called like
+
+ $st->cando( ACCESS, EFFECTIVE )
+
+where I<ACCESS> is one of C<S_IRUSR>, C<S_IWUSR> or C<S_IXUSR> from the
+L<Fcntl|Fcntl> module, and I<EFFECTIVE> indicates whether to use
+effective (true) or real (false) ids. The method interprets the C<mode>,
+C<uid> and C<gid> fields, and returns whether or not the current process
+would be allowed the specified access.
+
+If you don't want to use the objects, you may import the C<< ->cando >>
+method into your namespace as a regular function called C<stat_cando>.
+This takes an arrayref containing the return values of C<stat> or
+C<lstat> as its first argument, and interprets it for you.
+
 You may also import all the structure fields directly into your namespace
 as regular variables using the :FIELDS import tag.  (Note that this still
 overrides your stat() and lstat() functions.)  Access these fields as
@@ -276,6 +302,40 @@ and undocumented populate() function with CORE::stat():
 
     my $stat_obj = File::stat::populate(CORE::stat(_));
 
+=head1 ERRORS
+
+=over 4
+
+=item -%s is not implemented on a File::stat object
+
+The filetest operators C<-t>, C<-T> and C<-B> are not implemented, as
+they require more information than just a stat buffer.
+
+=back
+
+=head1 WARNINGS
+
+These can all be disabled with
+
+    no warnings "File::stat";
+
+=over 4
+
+=item File::stat ignores use filetest 'access'
+
+You have tried to use one of the C<-rwxRWX> filetests with C<use
+filetest 'access'> in effect. C<File::stat> will ignore the pragma, and
+just use the information in the C<mode> member as usual.
+
+=item File::stat ignores VMS ACLs
+
+VMS systems have a permissions structure that cannot be completely
+represented in a stat buffer, and unlike on other systems the builtin
+filetest operators respect this. The C<File::stat> overloads, however,
+do not, since the information required is not available.
+
+=back
+
 =head1 NOTE
 
 While this class is currently implemented using the Class::Struct