1File::chmod(3)        User Contributed Perl Documentation       File::chmod(3)
2
3
4

NAME

6       File::chmod - Implements symbolic and ls chmod modes
7

VERSION

9       version 0.42
10

SYNOPSIS

12         use File::chmod;
13         $File::chmod::UMASK = 0;
14         # It is recommended that you explicitly set $File::chmod::UMASK
15         # as the default will change in the future
16         #
17         # 0 is recommended to behave like system chmod
18         # 1 if you want File::chmod to apply your environment set umask.
19         # 2 is how we detect that it's internally set, undef will become the
20         # default in the future, eventually a lexicaly scoped API may be designed
21
22         # chmod takes all three types
23         # these all do the same thing
24         chmod(0666,@files);
25         chmod("=rw",@files);
26         chmod("-rw-rw-rw-",@files);
27
28         # or
29
30         use File::chmod qw( symchmod lschmod );
31
32         chmod(0666,@files);           # this is the normal chmod
33         symchmod("=rw",@files);       # takes symbolic modes only
34         lschmod("-rw-rw-rw-",@files); # takes "ls" modes only
35
36         # more functions, read on to understand
37

DESCRIPTION

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
66       a 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
82       on each file.
83

FUNCTIONS - EXPORT

85   chmod(MODE,FILES)
86       Takes an octal, symbolic, or "ls" mode, and then chmods each file
87       appropriately.
88
89   getchmod(MODE,FILES)
90       Returns a list of modified permissions, without chmodding files.
91       Accepts any of the three kinds of modes.
92
93         @newmodes = getchmod("+x","file1","file2");
94         # @newmodes holds the octal permissions of the files'
95         # modes, if they were to be sent through chmod("+x"...)
96

FUNCTIONS - EXPORT_OK

98   symchmod(MODE,FILES)
99       Takes a symbolic permissions mode, and chmods each file.
100
101   lschmod(MODE,FILES)
102       Takes an "ls" permissions mode, and chmods each file.
103
104   getsymchmod(MODE,FILES)
105       Returns a list of modified permissions, without chmodding files.
106       Accepts only symbolic permission modes.
107
108   getlschmod(MODE,FILES)
109       Returns a list of modified permissions, without chmodding files.
110       Accepts only "ls" permission modes.
111
112   getmod(FILES)
113       Returns a list of the current mode of each file.
114

VARIABLES

116   $File::chmod::DEBUG
117       If set to a true value, it will report warnings, similar to those
118       produced by chmod() on your system.  Otherwise, the functions will not
119       report errors.  Example: a file can not have file-locking and the set-
120       gid bits on at the same time.  If $File::chmod::DEBUG is true, the
121       function will report an error.  If not, you are not warned of the
122       conflict.  It is set to 1 as default.
123
124   $File::chmod::MASK
125       Contains the umask to apply to new file modes when using getsymchmod().
126       This defaults to the return value of umask() at compile time.  Is only
127       applied if $UMASK is true.
128
129   $File::chmod::UMASK
130       This is a boolean which tells getsymchmod() whether or not to apply the
131       umask found in $MASK.  It defaults to true.
132

PORTING

134       This is only good on Unix-like boxes.  I would like people to help me
135       work on File::chmod for any OS that deserves it.  If you would like to
136       help, please email me (address below) with the OS and any information
137       you might have on how chmod() should work on it; if you don't have any
138       specific information, but would still like to help, hey, that's good
139       too.  I have the following information (from "perlport"):
140
141       Win32
142           Only good for changing "owner" read-write access, "group", and
143           "other" bits are meaningless.  NOTE: Win32::File and
144           Win32::FileSecurity already do this.  I do not currently see a need
145           to port File::chmod.
146
147       MacOS
148           Only limited meaning. Disabling/enabling write permission is mapped
149           to locking/unlocking the file.
150
151       RISC OS
152           Only good for changing "owner" and "other" read-write access.
153

SEE ALSO

155         Stat::lsMode (by Mark-James Dominus, CPAN ID: MJD)
156         chmod(1) manpage
157         perldoc -f chmod
158         perldoc -f stat
159

BUGS

161       Please report any bugs or feature requests on the bugtracker website
162       https://github.com/xenoterracide/file-chmod/issues
163
164       When submitting a bug or request, please include a test-file or a patch
165       to an existing test-file that illustrates the bug or desired feature.
166

CONTRIBUTORS

168       •   David Steinbrunner <dsteinbrunner@pobox.com>
169
170       •   Slaven Rezic <slaven@rezic.de>
171
172       •   Steve Throckmorton <arrestee@gmail.com>
173
174       •   Tim <oylenshpeegul@gmail.com>
175

AUTHORS

177       •   Jeff Pinyan <japhy.734+CPAN@gmail.com>
178
179       •   Caleb Cushing <xenoterracide@gmail.com>
180
182       This software is copyright (c) 2015 by Caleb Cushing and Jeff Pinyan.
183
184       This is free software; you can redistribute it and/or modify it under
185       the same terms as the Perl 5 programming language system itself.
186
187
188
189perl v5.38.0                      2023-07-20                    File::chmod(3)
Impressum