lib/filetest.pm

   1 package filetest;
   2
   3 our $VERSION = '1.01';
   4
   5 =head1 NAME
   6
   7 filetest - Perl pragma to control the filetest permission operators
   8
   9 =head1 SYNOPSIS
  10
  11     $can_perhaps_read = -r "file";      # use the mode bits
  12     {
  13         use filetest 'access';          # intuit harder
  14         $can_really_read = -r "file";
  15     }
  16     $can_perhaps_read = -r "file";      # use the mode bits again
  17
  18 =head1 DESCRIPTION
  19
  20 This pragma tells the compiler to change the behaviour of the filetest
  21 permission operators, C<-r> C<-w> C<-x> C<-R> C<-W> C<-X>
  22 (see L<perlfunc>).
  23
  24 The default behaviour is to use the mode bits as returned by the stat()
  25 family of calls.  This, however, may not be the right thing to do if
  26 for example various ACL (access control lists) schemes are in use.
  27 For such environments, C<use filetest> may help the permission
  28 operators to return results more consistent with other tools.
  29
  30 Each "use filetest" or "no filetest" affects statements to the end of
  31 the enclosing block.
  32
  33 There may be a slight performance decrease in the filetests
  34 when C<use filetest> is in effect, because in some systems
  35 the extended functionality needs to be emulated.
  36
  37 B<NOTE>: using the file tests for security purposes is a lost cause
  38 from the start: there is a window open for race conditions (who is to
  39 say that the permissions will not change between the test and the real
  40 operation?).  Therefore if you are serious about security, just try
  41 the real operation and test for its success - think in terms of atomic
  42 operations.
  43
  44 =head2 subpragma access
  45
  46 Currently only one subpragma, C<access> is implemented.  It enables
  47 (or disables) the use of access() or similar system calls.  This
  48 extended filetest functionality is used only when the argument of the
  49 operators is a filename, not when it is a filehandle.
  50
  51 =cut
  52
  53 $filetest::hint_bits = 0x00400000; # HINT_FILETEST_ACCESS
  54
  55 sub import {
  56     if ( $_[1] eq 'access' ) {
  57         $^H |= $filetest::hint_bits;
  58     } else {
  59         die "filetest: the only implemented subpragma is 'access'.\n";
  60     }
  61 }
  62
  63 sub unimport {
  64     if ( $_[1] eq 'access' ) {
  65         $^H &= ~$filetest::hint_bits;
  66     } else {
  67         die "filetest: the only implemented subpragma is 'access'.\n";
  68     }
  69 }
  70
  71 1;