Commit | Line | Data |
---|---|---|
5ff3f7a4 GS |
1 | package filetest; |
2 | ||
f703fc96 | 3 | our $VERSION = '1.03'; |
b75c8c73 | 4 | |
5ff3f7a4 GS |
5 | =head1 NAME |
6 | ||
7 | filetest - Perl pragma to control the filetest permission operators | |
8 | ||
9 | =head1 SYNOPSIS | |
3cb6de81 | 10 | |
5ff3f7a4 GS |
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 | |
feaeca78 | 21 | permission operators, C<-r> C<-w> C<-x> C<-R> C<-W> C<-X> |
80d06f2d | 22 | (see L<perlfunc>). |
5ff3f7a4 | 23 | |
ecae030f MO |
24 | The default behaviour of file test operators is to use the simple |
25 | mode bits as returned by the stat() family of system calls. However, | |
26 | many operating systems have additional features to define more complex | |
27 | access rights, for example ACLs (Access Control Lists). | |
5ff3f7a4 GS |
28 | For such environments, C<use filetest> may help the permission |
29 | operators to return results more consistent with other tools. | |
30 | ||
ecae030f MO |
31 | The C<use filetest> or C<no filetest> statements affect file tests defined in |
32 | their block, up to the end of the closest enclosing block (they are lexically | |
33 | block-scoped). | |
5ff3f7a4 | 34 | |
ecae030f MO |
35 | Currently, only the C<access> sub-pragma is implemented. It enables (or |
36 | disables) the use of access() when available, that is, on most UNIX systems and | |
37 | other POSIX environments. See details below. | |
5ff3f7a4 | 38 | |
ecae030f MO |
39 | =head2 Consider this carefully |
40 | ||
41 | The stat() mode bits are probably right for most of the files and | |
42 | directories found on your system, because few people want to use the | |
43 | additional features offered by access(). But you may encounter surprises | |
44 | if your program runs on a system that uses ACLs, since the stat() | |
45 | information won't reflect the actual permissions. | |
46 | ||
47 | There may be a slight performance decrease in the filetest operations | |
48 | when the filetest pragma is in effect, because checking bits is very | |
49 | cheap. | |
50 | ||
51 | Also, note that using the file tests for security purposes is a lost cause | |
80d06f2d JH |
52 | from the start: there is a window open for race conditions (who is to |
53 | say that the permissions will not change between the test and the real | |
54 | operation?). Therefore if you are serious about security, just try | |
9b488eb8 | 55 | the real operation and test for its success - think in terms of atomic |
ecae030f MO |
56 | operations. Filetests are more useful for filesystem administrative |
57 | tasks, when you have no need for the content of the elements on disk. | |
58 | ||
59 | =head2 The "access" sub-pragma | |
60 | ||
61 | UNIX and POSIX systems provide an abstract access() operating system call, | |
62 | which should be used to query the read, write, and execute rights. This | |
63 | function hides various distinct approaches in additional operating system | |
64 | specific security features, like Access Control Lists (ACLs) | |
65 | ||
66 | The extended filetest functionality is used by Perl only when the argument | |
67 | of the operators is a filename, not when it is a filehandle. | |
68 | ||
69 | =head2 Limitation with regard to C<_> | |
70 | ||
71 | Because access() does not invoke stat() (at least not in a way visible | |
72 | to Perl), B<the stat result cache "_" is not set>. This means that the | |
73 | outcome of the following two tests is different. The first has the stat | |
f703fc96 | 74 | bits of F</etc/passwd> in C<_>, and in the second case this still |
ecae030f MO |
75 | contains the bits of C</etc>. |
76 | ||
77 | { -d '/etc'; | |
78 | -w '/etc/passwd'; | |
79 | print -f _ ? 'Yes' : 'No'; # Yes | |
80 | } | |
81 | ||
82 | { use filetest 'access'; | |
83 | -d '/etc'; | |
84 | -w '/etc/passwd'; | |
85 | print -f _ ? 'Yes' : 'No'; # No | |
86 | } | |
87 | ||
88 | Of course, unless your OS does not implement access(), in which case the | |
89 | pragma is simply ignored. Best not to use C<_> at all in a file where | |
90 | the filetest pragma is active! | |
5ff3f7a4 | 91 | |
ecae030f MO |
92 | As a side effect, as C<_> doesn't work, stacked filetest operators |
93 | (C<-f -w $file>) won't work either. | |
5ff3f7a4 | 94 | |
ecae030f | 95 | This limitation might be removed in a future version of perl. |
5ff3f7a4 GS |
96 | |
97 | =cut | |
98 | ||
9cfe5470 | 99 | $filetest::hint_bits = 0x00400000; # HINT_FILETEST_ACCESS |
d5448623 | 100 | |
5ff3f7a4 GS |
101 | sub import { |
102 | if ( $_[1] eq 'access' ) { | |
d5448623 | 103 | $^H |= $filetest::hint_bits; |
5ff3f7a4 GS |
104 | } else { |
105 | die "filetest: the only implemented subpragma is 'access'.\n"; | |
106 | } | |
107 | } | |
108 | ||
109 | sub unimport { | |
110 | if ( $_[1] eq 'access' ) { | |
d5448623 | 111 | $^H &= ~$filetest::hint_bits; |
5ff3f7a4 GS |
112 | } else { |
113 | die "filetest: the only implemented subpragma is 'access'.\n"; | |
114 | } | |
115 | } | |
116 | ||
117 | 1; |