| 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 |
|