1chmod(3) User Contributed Perl Documentation chmod(3)
2
6 File::chmod - Implements symbolic and ls chmod modes
7
9 This is File::chmod v0.32.
10
12 use File::chmod;
13 # chmod takes all three types
15 # these all do the same thing
16 chmod(0666,@files);
17 chmod("=rw",@files);
18 chmod("-rw-rw-rw-",@files);
19 # or
21 use File::chmod qw( symchmod lschmod );
23 chmod(0666,@files); # this is the normal chmod
25 symchmod("=rw",@files); # takes symbolic modes only
26 lschmod("-rw-rw-rw-",@files); # takes "ls" modes only
27 # more functions, read on to understand
29
31 File::chmod is a utility that allows you to bypass system calls or bit
32 processing of a file's permissions. It overloads the chmod() function
33 with its own that gets an octal mode, a symbolic mode (see below), or
34 an "ls" mode (see below). If you wish not to overload chmod(), you can
35 export symchmod() and lschmod(), which take, respectively, a symbolic
36 mode and an "ls" mode.
37 Symbolic modes are thoroughly described in your chmod(1) man page, but
39 here are a few examples.
40 # NEW: if $UMASK is true, symchmod() applies a bit-mask found in $MASK
42 chmod("+x","file1","file2"); # overloaded chmod(), that is...
44 # turns on the execute bit for all users on those two files
45 chmod("o=,g-w","file1","file2");
47 # removes 'other' permissions, and the write bit for 'group'
48 chmod("=u","file1","file2");
50 # sets all bits to those in 'user'
51 "ls" modes are the type produced on the left-hand side of an "ls -l" on
53 a directory. Examples are:
54 chmod("-rwxr-xr-x","file1","file2");
56 # the 0755 setting; user has read-write-execute, group and others
57 # have read-execute priveleges
58 chmod("-rwsrws---","file1","file2");
60 # sets read-write-execute for user and group, none for others
61 # also sets set-uid and set-gid bits
62 The regular chmod() and lschmod() are absolute; that is, they are not
64 appending to or subtracting from the current file mode. They set it,
65 regardless of what it had been before. symchmod() is useful for allow‐
66 ing the modifying of a file's permissions without having to run a sys‐
67 tem call or determining the file's permissions, and then combining that
68 with whatever bits are appropriate. It also operates separately on
69 each file.
70 An added feature to version 0.30 is the $UMASK variable, explained
72 below; if symchmod() is called and this variable is true, then the
73 function uses the (also new) $MASK variable (which defaults to umask())
74 as a mask against the new mode. This is documented below more clearly.
75 Functions
77 Exported by default:
79 chmod(MODE,FILES)
81 Takes an octal, symbolic, or "ls" mode, and then chmods each file
82 appropriately.
83 getchmod(MODE,FILES)
85 Returns a list of modified permissions, without chmodding files.
86 Accepts any of the three kinds of modes.
87 @newmodes = getchmod("+x","file1","file2");
89 # @newmodes holds the octal permissons of the files'
90 # modes, if they were to be sent through chmod("+x"...)
91 Exported by request:
93 symchmod(MODE,FILES)
95 Takes a symbolic permissions mode, and chmods each file.
96 lschmod(MODE,FILES)
98 Takes an "ls" permissions mode, and chmods each file.
99 getsymchmod(MODE,FILES)
101 Returns a list of modified permissions, without chmodding files.
102 Accepts only symbolic permisson modes.
103 getlschmod(MODE,FILES)
105 Returns a list of modified permissions, without chmodding files.
106 Accepts only "ls" permisson modes.
107 getmod(FILES)
109 Returns a list of the current mode of each file.
110 Variables
112 $File::chmod::DEBUG
114 If set to a true value, it will report warnings, similar to those
115 produced by chmod() on your system. Otherwise, the functions will
116 not report errors. Example: a file can not have file-locking and
117 the set-gid bits on at the same time. If $File::chmod::DEBUG is
118 true, the function will report an error. If not, you are not
119 warned of the conflict. It is set to 1 as default.
120 $File::chmod::MASK
122 Contains the umask to apply to new file modes when using getsymch‐
123 mod(). This defaults to the return value of umask() at compile
124 time. Is only applied if $UMASK is true.
125 $File::chmod::UMASK
127 This is a boolean which tells getsymchmod() whether or not to apply
128 the umask found in $MASK. It defaults to true.
129
131 Note: this section was started with version 0.30.
132 This is an in-depth look at the changes being made from version to ver‐
134 sion.
135 0.31 to 0.32
137 license added
139 I added a license to this module so that it can be used places
140 without asking my permission. Sorry, Adam.
141 0.30 to 0.31
143 fixed getsymchmod() bug
145 Whoa. getsymchmod() was doing some crazy ish. That's about all I
146 can say. I did a great deal of debugging, and fixed it up. It ALL
147 had to do with two things:
148 $or = (/+=/ ? 1 : 0); # should have been /[+=]/
150 /u/ && $ok ? u_or() : u_not(); # should have been /u/ and $ok
152 fixed getmod() bug
154 I was using map() incorrectly in getmod(). Fixed that.
155 condensed lschmod()
157 I shorted it up, getting rid a variable.
158 0.21 to 0.30
160 added umask() honoring for symchmod()
162 The symchmod() function now honors the $UMASK and $MASK variables.
163 $UMASK is a boolean which indicates whether or not to honor the
164 $MASK variable. $MASK holds a umask, and it defaults to umask().
165 $UMASK defaults to true. These variables are NOT exported. They
166 must explictly set (i.e. $File::chmod::UMASK = 0).
167 function name changes
169 Renamed internal function determine_mode() to mode(). However, if
170 you happen to be using determine_mode() somewhere, mode() will be
171 called, but you'll also get a warning about deprecation.
172 Renamed internal functions {or,not}_{l,s,t} to {l,s,t}_{or,not}.
174 This is to keep in standard with the OTHER 6 pairs of bitwise func‐
175 tions, such as r_or() and g_not(). I don't know WHY the others had
176 'not' or 'or' in the front.
177 fixed debugging bugs
179 Certain calls to warn() were not guarded by the $DEBUG variable,
180 and now they are. Also, for some reason, I left a debugging check
181 (that didn't check to see if $DEBUG was true) in getsymchmod(),
182 line 118. It printed "ENTERING /g/". It's gone now.
183 fixed set-uid and set-gid bug
185 Heh, it seems that in the previous version of File::chmod, the fol‐
186 lowing code went along broken:
187 # or_s sub, File/chmod.pm, v0.21, line 330
189 ($VAL & 00100) && do {
190 $DEBUG && warn("execute bit must be on for set-uid"); 1;
191 } && next;
192 Aside from me using '&&' more than enough (changed in the new
194 code), this is broken. This is now fixed.
195 fixed file lock/set-gid bug
197 The not_l() function (now renamed to l_not()) used to take the file
198 mode and bit-wise NOT it with ~02000. However, it did not check if
199 the file was locked vs. set-gid. Now, the function is "$VAL &=
200 ~02000 if not $VAL & 00010;".
201 removed useless data structures
203 I do not know why I had the $S variable, or %r, %w, and %x hashes.
204 In fact, $S was declared in "use vars qw( ... );", but never given
205 a value, and the %r, %w, and %x hashes had a 'full' key which never
206 got used. And the hashes themselves weren't really needed anyway.
207 Here is a list of the variables no longer in use, and what they
208 have been replaced with (if any):
209 $S nothing
211 $U, $G, $O $W
212 %r, %w, %x octal numbers
213 @files @_ (I had @files = @_; in nearly EVERY sub)
214 $c $_
215 compacted code
217 The first version of File::chmod that was published was 0.13, and
218 it was written in approximately 10 days, being given the off-and-on
219 treatment I end up having to give several projects, due to more
220 pressing matters. Well, since then, most of the code has stayed
221 the same, although bugs were worked out. Well, I got rid of a lot
222 of slow, clunky, and redundant sections of code in this version.
223 Sections include the processing of each character of the mode in
224 getsymchmod(), the getmod() subroutine, um, nearly ALL of the get‐
225 symchmod() function, now that I look at it.
226 Here's part of the getsymchmod() rewrite:
228 for ($c){
230 if (/u/){
231 u_or() if $MODE eq "+" or $MODE eq "=";
232 u_not() if $MODE eq "-";
233 }
234 ...
235 }
236 # changed to
238 /u/ && $or ? u_or() : u_and();
240 # note: operating on $_, $c isn't used anymore
241 # note: $or holds 1 if the $MODE was + or =, 0 if $MODE was -
242 # note: previous was redundant. didn't need $MODE eq "-" check
243 # because u_or() and u_not() both go to the next character
244
246 This is only good on Unix-like boxes. I would like people to help me
247 work on File::chmod for any OS that deserves it. If you would like to
248 help, please email me (address below) with the OS and any information
249 you might have on how chmod() should work on it; if you don't have any
250 specific information, but would still like to help, hey, that's good
251 too. I have the following information (from "perlport"):
252 Win32
254 Only good for changing "owner" read-write access, "group", and
255 "other" bits are meaningless. NOTE: Win32::File and Win32::FileSe‐
256 curity already do this. I do not currently see a need to port
257 File::chmod.
258 MacOS
260 Only limited meaning. Disabling/enabling write permission is mapped
261 to locking/unlocking the file.
262 RISC OS
264 Only good for changing "owner" and "other" read-write access.
265
267 Jeff "japhy" Pinyan, japhy.734+CPAN@gmail.com, CPAN ID: PINYAN
268
270 Stat::lsMode (by Mark-James Dominus, CPAN ID: MJD)
271 chmod(1) manpage
272 perldoc -f chmod
273 perldoc -f stat
274
276 Copyright (C) 2007 by Jeff Pinyan
277 This library is free software; you can redistribute it and/or modify it
279 under the same terms as Perl itself, either Perl version 5.8.8 or, at
280 your option, any later version of Perl 5 you may have available.
281perl v5.8.8 2007-07-28 chmod(3)