X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Ffiletest.pm;h=b08f1dc910705f5db324baec8956ad25ba5658c9;hb=aaf9c2b26697492a8234a7efe890beef8868ea9b;hp=cc14e82817cc6eac8e8e4504ff254a7c4e7d0cfd;hpb=5ff3f7a4e03a6b103d9e628865398e498e9a7968;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/lib/filetest.pm b/lib/filetest.pm
index cc14e82..b08f1dc 100644
--- a/lib/filetest.pm
+++ b/lib/filetest.pm
@@ -1,11 +1,13 @@
 package filetest;
 
+our $VERSION = '1.02';
+
 =head1 NAME
 
 filetest - Perl pragma to control the filetest permission operators
 
 =head1 SYNOPSIS
-    
+
     $can_perhaps_read = -r "file";	# use the mode bits
     {
         use filetest 'access';		# intuit harder
@@ -16,39 +18,89 @@ filetest - Perl pragma to control the filetest permission operators
 =head1 DESCRIPTION
 
 This pragma tells the compiler to change the behaviour of the filetest
-permissions operators, the -r -w -x -R -W -X (see L<perlfunc>).
+permission operators, C<-r> C<-w> C<-x> C<-R> C<-W> C<-X>
+(see L<perlfunc>).
 
-The default behaviour to use the mode bits as returned by the stat()
-family of calls.  This, however, may not be the right thing to do if
-for example various ACL (access control lists) schemes are in use.
+The default behaviour of file test operators is to use the simple
+mode bits as returned by the stat() family of system calls.  However,
+many operating systems have additional features to define more complex
+access rights, for example ACLs (Access Control Lists).
 For such environments, C<use filetest> may help the permission
 operators to return results more consistent with other tools.
 
-Each "use filetest" or "no filetest" affects statements to the end of
-the enclosing block.
+The C<use filetest> or C<no filetest> statements affect file tests defined in
+their block, up to the end of the closest enclosing block (they are lexically
+block-scoped).
+
+Currently, only the C<access> sub-pragma is implemented.  It enables (or
+disables) the use of access() when available, that is, on most UNIX systems and
+other POSIX environments.  See details below.
+
+=head2 Consider this carefully
+
+The stat() mode bits are probably right for most of the files and
+directories found on your system, because few people want to use the
+additional features offered by access(). But you may encounter surprises
+if your program runs on a system that uses ACLs, since the stat()
+information won't reflect the actual permissions.
+
+There may be a slight performance decrease in the filetest operations
+when the filetest pragma is in effect, because checking bits is very
+cheap.
+
+Also, note that using the file tests for security purposes is a lost cause
+from the start: there is a window open for race conditions (who is to
+say that the permissions will not change between the test and the real
+operation?).  Therefore if you are serious about security, just try
+the real operation and test for its success - think in terms of atomic
+operations.  Filetests are more useful for filesystem administrative
+tasks, when you have no need for the content of the elements on disk.
 
-There may be a slight performance decrease in the filetests
-when C<use filetest> is in effect, because in some systems
-the extended functionality needs to be emulated.
+=head2 The "access" sub-pragma
 
-B<NOTE>: using the file tests is a lost case from the start: there is
-a window open for race conditions (who is to say that the permissions
-will not change between the test and the real operation?).  Therefore
-if you are serious about security, just try the real operation and
-test for its success.  Think atomicity.
+UNIX and POSIX systems provide an abstract access() operating system call,
+which should be used to query the read, write, and execute rights. This
+function hides various distinct approaches in additional operating system
+specific security features, like Access Control Lists (ACLs)
 
-=head2 subpragma access
+The extended filetest functionality is used by Perl only when the argument
+of the operators is a filename, not when it is a filehandle.
 
-Currently only one subpragma, C<access> is implemented.  It enables
-(or disables) the use of access() or similar system calls.  This
-extended filetest functionality is used only when the argument of the
-operators is a filename, not when it is a filehandle.
+=head2 Limitation with regard to C<_>
+
+Because access() does not invoke stat() (at least not in a way visible
+to Perl), B<the stat result cache "_" is not set>.  This means that the
+outcome of the following two tests is different.  The first has the stat
+bits of C</etc/passwd> in C<_>, and in the second case this still
+contains the bits of C</etc>.
+
+ { -d '/etc';
+   -w '/etc/passwd';
+   print -f _ ? 'Yes' : 'No';   # Yes
+ }
+
+ { use filetest 'access';
+   -d '/etc';
+   -w '/etc/passwd';
+   print -f _ ? 'Yes' : 'No';   # No
+ }
+
+Of course, unless your OS does not implement access(), in which case the
+pragma is simply ignored.  Best not to use C<_> at all in a file where
+the filetest pragma is active!
+
+As a side effect, as C<_> doesn't work, stacked filetest operators
+(C<-f -w $file>) won't work either.
+
+This limitation might be removed in a future version of perl.
 
 =cut
 
+$filetest::hint_bits = 0x00400000; # HINT_FILETEST_ACCESS
+
 sub import {
     if ( $_[1] eq 'access' ) {
-	$^H |= 0x00400000;
+	$^H |= $filetest::hint_bits;
     } else {
 	die "filetest: the only implemented subpragma is 'access'.\n";
     }
@@ -56,7 +108,7 @@ sub import {
 
 sub unimport {
     if ( $_[1] eq 'access' ) {
-	$^H &= ~0x00400000;
+	$^H &= ~$filetest::hint_bits;
     } else {
 	die "filetest: the only implemented subpragma is 'access'.\n";
     }