Debian Codegraph @

README

raw
1 NAME
2
3 File::chmod - Implements symbolic and ls chmod modes
4
5 VERSION
6
7 version 0.42
8
9 SYNOPSIS
10
11 use File::chmod;
12 $File::chmod::UMASK = 0;
13 # It is recommended that you explicitly set $File::chmod::UMASK
14 # as the default will change in the future
15 #
16 # 0 is recommended to behave like system chmod
17 # 1 if you want File::chmod to apply your environment set umask.
18 # 2 is how we detect that it's internally set, undef will become the
19 # default in the future, eventually a lexicaly scoped API may be designed
20
21 # chmod takes all three types
22 # these all do the same thing
23 chmod(0666,@files);
24 chmod("=rw",@files);
25 chmod("-rw-rw-rw-",@files);
26
27 # or
28
29 use File::chmod qw( symchmod lschmod );
30
31 chmod(0666,@files); # this is the normal chmod
32 symchmod("=rw",@files); # takes symbolic modes only
33 lschmod("-rw-rw-rw-",@files); # takes "ls" modes only
34
35 # more functions, read on to understand
36
37 DESCRIPTION
38
39 File::chmod is a utility that allows you to bypass system calls or bit
40 processing of a file's permissions. It overloads the chmod() function
41 with its own that gets an octal mode, a symbolic mode (see below), or
42 an "ls" mode (see below). If you wish not to overload chmod(), you can
43 export symchmod() and lschmod(), which take, respectively, a symbolic
44 mode and an "ls" mode.
45
46 An added feature to version 0.30 is the $UMASK variable, explained in
47 detail below; if symchmod() is called and this variable is true, then
48 the function uses the (also new) $MASK variable (which defaults to
49 umask()) as a mask against the new mode. This mode is on by default,
50 and changes the behavior from what you would expect if you are used to
51 UNIX chmod. This may change in the future.
52
53 Symbolic modes are thoroughly described in your chmod(1) man page, but
54 here are a few examples.
55
56 chmod("+x","file1","file2"); # overloaded chmod(), that is...
57 # turns on the execute bit for all users on those two files
58
59 chmod("o=,g-w","file1","file2");
60 # removes 'other' permissions, and the write bit for 'group'
61
62 chmod("=u","file1","file2");
63 # sets all bits to those in 'user'
64
65 "ls" modes are the type produced on the left-hand side of an ls -l on a
66 directory. Examples are:
67
68 chmod("-rwxr-xr-x","file1","file2");
69 # the 0755 setting; user has read-write-execute, group and others
70 # have read-execute priveleges
71
72 chmod("-rwsrws---","file1","file2");
73 # sets read-write-execute for user and group, none for others
74 # also sets set-uid and set-gid bits
75
76 The regular chmod() and lschmod() are absolute; that is, they are not
77 appending to or subtracting from the current file mode. They set it,
78 regardless of what it had been before. symchmod() is useful for
79 allowing the modifying of a file's permissions without having to run a
80 system call or determining the file's permissions, and then combining
81 that with whatever bits are appropriate. It also operates separately on
82 each file.
83
84 FUNCTIONS - EXPORT
85
86 chmod(MODE,FILES)
87
88 Takes an octal, symbolic, or "ls" mode, and then chmods each file
89 appropriately.
90
91 getchmod(MODE,FILES)
92
93 Returns a list of modified permissions, without chmodding files.
94 Accepts any of the three kinds of modes.
95
96 @newmodes = getchmod("+x","file1","file2");
97 # @newmodes holds the octal permissions of the files'
98 # modes, if they were to be sent through chmod("+x"...)
99
100 FUNCTIONS - EXPORT_OK
101
102 symchmod(MODE,FILES)
103
104 Takes a symbolic permissions mode, and chmods each file.
105
106 lschmod(MODE,FILES)
107
108 Takes an "ls" permissions mode, and chmods each file.
109
110 getsymchmod(MODE,FILES)
111
112 Returns a list of modified permissions, without chmodding files.
113 Accepts only symbolic permission modes.
114
115 getlschmod(MODE,FILES)
116
117 Returns a list of modified permissions, without chmodding files.
118 Accepts only "ls" permission modes.
119
120 getmod(FILES)
121
122 Returns a list of the current mode of each file.
123
124 VARIABLES
125
126 $File::chmod::DEBUG
127
128 If set to a true value, it will report warnings, similar to those
129 produced by chmod() on your system. Otherwise, the functions will not
130 report errors. Example: a file can not have file-locking and the
131 set-gid bits on at the same time. If $File::chmod::DEBUG is true, the
132 function will report an error. If not, you are not warned of the
133 conflict. It is set to 1 as default.
134
135 $File::chmod::MASK
136
137 Contains the umask to apply to new file modes when using getsymchmod().
138 This defaults to the return value of umask() at compile time. Is only
139 applied if $UMASK is true.
140
141 $File::chmod::UMASK
142
143 This is a boolean which tells getsymchmod() whether or not to apply the
144 umask found in $MASK. It defaults to true.
145
146 PORTING
147
148 This is only good on Unix-like boxes. I would like people to help me
149 work on File::chmod for any OS that deserves it. If you would like to
150 help, please email me (address below) with the OS and any information
151 you might have on how chmod() should work on it; if you don't have any
152 specific information, but would still like to help, hey, that's good
153 too. I have the following information (from "perlport"):
154
155 Win32
156
157 Only good for changing "owner" read-write access, "group", and
158 "other" bits are meaningless. NOTE: Win32::File and
159 Win32::FileSecurity already do this. I do not currently see a need to
160 port File::chmod.
161
162 MacOS
163
164 Only limited meaning. Disabling/enabling write permission is mapped
165 to locking/unlocking the file.
166
167 RISC OS
168
169 Only good for changing "owner" and "other" read-write access.
170
171 SEE ALSO
172
173 Stat::lsMode (by Mark-James Dominus, CPAN ID: MJD)
174 chmod(1) manpage
175 perldoc -f chmod
176 perldoc -f stat
177
178 BUGS
179
180 Please report any bugs or feature requests on the bugtracker website
181 https://github.com/xenoterracide/file-chmod/issues
182
183 When submitting a bug or request, please include a test-file or a patch
184 to an existing test-file that illustrates the bug or desired feature.
185
186 CONTRIBUTORS
187
188 * David Steinbrunner <[email protected]>
189
190 * Slaven Rezic <[email protected]>
191
192 * Steve Throckmorton <[email protected]>
193
194 * Tim <[email protected]>
195
196 AUTHORS
197
198 * Jeff Pinyan <[email protected]>
199
200 * Caleb Cushing <[email protected]>
201
202 COPYRIGHT AND LICENSE
203
204 This software is copyright (c) 2015 by Caleb Cushing and Jeff Pinyan.
205
206 This is free software; you can redistribute it and/or modify it under
207 the same terms as the Perl 5 programming language system itself.
208