NAME¶
File::chmod - Implements symbolic and ls chmod modes
VERSION¶
version 0.40
SYNOPSIS¶
use File::chmod;
$File::chmod::UMASK = 0; # you may want this, it ignores the systems umask setting
# chmod takes all three types
# these all do the same thing
chmod(0666,@files);
chmod("=rw",@files);
chmod("-rw-rw-rw-",@files);
# or
use File::chmod qw( symchmod lschmod );
chmod(0666,@files); # this is the normal chmod
symchmod("=rw",@files); # takes symbolic modes only
lschmod("-rw-rw-rw-",@files); # takes "ls" modes only
# more functions, read on to understand
DESCRIPTION¶
File::chmod is a utility that allows you to bypass system calls or bit
processing of a file's permissions. It overloads the
chmod() function
with its own that gets an octal mode, a symbolic mode (see below), or an
"ls" mode (see below). If you wish not to overload
chmod(),
you can export
symchmod() and
lschmod(), which take,
respectively, a symbolic mode and an "ls" mode.
An added feature to version 0.30 is the $UMASK variable, explained in detail
below; if "symchmod()" is called and this variable is true, then the
function uses the (also new) $MASK variable (which defaults to
"umask()") as a mask against the new mode. This mode is on by
default, and changes the behavior from what you would expect if you are used
to UNIX "chmod".
Symbolic modes are thoroughly described in your
chmod(1) man page, but
here are a few examples.
chmod("+x","file1","file2"); # overloaded chmod(), that is...
# turns on the execute bit for all users on those two files
chmod("o=,g-w","file1","file2");
# removes 'other' permissions, and the write bit for 'group'
chmod("=u","file1","file2");
# sets all bits to those in 'user'
"ls" modes are the type produced on the left-hand side of an "ls
-l" on a directory. Examples are:
chmod("-rwxr-xr-x","file1","file2");
# the 0755 setting; user has read-write-execute, group and others
# have read-execute priveleges
chmod("-rwsrws---","file1","file2");
# sets read-write-execute for user and group, none for others
# also sets set-uid and set-gid bits
The regular
chmod() and
lschmod() are absolute; that is, they are
not appending to or subtracting from the current file mode. They set it,
regardless of what it had been before.
symchmod() is useful for
allowing the modifying of a file's permissions without having to run a system
call or determining the file's permissions, and then combining that with
whatever bits are appropriate. It also operates separately on each file.
FUNCTIONS - EXPORT¶
chmod(MODE,FILES)¶
Takes an octal, symbolic, or "ls" mode, and then chmods each file
appropriately.
getchmod(MODE,FILES)¶
Returns a list of modified permissions, without chmodding files. Accepts any of
the three kinds of modes.
@newmodes = getchmod("+x","file1","file2");
# @newmodes holds the octal permissions of the files'
# modes, if they were to be sent through chmod("+x"...)
FUNCTIONS - EXPORT_OK¶
symchmod(MODE,FILES)¶
Takes a symbolic permissions mode, and chmods each file.
lschmod(MODE,FILES)¶
Takes an "ls" permissions mode, and chmods each file.
getsymchmod(MODE,FILES)¶
Returns a list of modified permissions, without chmodding files. Accepts only
symbolic permission modes.
getlschmod(MODE,FILES)¶
Returns a list of modified permissions, without chmodding files. Accepts only
"ls" permission modes.
getmod(FILES)¶
Returns a list of the current mode of each file.
VARIABLES¶
$File::chmod::DEBUG¶
If set to a true value, it will report warnings, similar to those produced by
chmod() on your system. Otherwise, the functions will not report
errors. Example: a file can not have file-locking and the set-gid bits on at
the same time. If $File::chmod::DEBUG is true, the function will report an
error. If not, you are not warned of the conflict. It is set to 1 as default.
$File::chmod::MASK¶
Contains the umask to apply to new file modes when using
getsymchmod().
This defaults to the return value of
umask() at compile time. Is only
applied if $UMASK is true.
$File::chmod::UMASK¶
This is a boolean which tells
getsymchmod() whether or not to apply the
umask found in $MASK. It defaults to true.
PORTING¶
This is only good on Unix-like boxes. I would like people to help me work on
File::chmod for any OS that deserves it. If you would like to help, please
email me (address below) with the OS and any information you might have on how
chmod() should work on it; if you don't have any specific information,
but would still like to help, hey, that's good too. I have the following
information (from "perlport"):
- Win32
- Only good for changing "owner" read-write access,
"group", and "other" bits are meaningless. NOTE:
Win32::File and Win32::FileSecurity already do this. I do not
currently see a need to port File::chmod.
- MacOS
- Only limited meaning. Disabling/enabling write permission is mapped to
locking/unlocking the file.
- RISC OS
- Only good for changing "owner" and "other" read-write
access.
SEE ALSO¶
Stat::lsMode (by Mark-James Dominus, CPAN ID: MJD)
chmod(1) manpage
perldoc -f chmod
perldoc -f stat
BUGS¶
Please report any bugs or feature requests on the bugtracker website
https://github.com/xenoterracide/file-chmod/issues
When submitting a bug or request, please include a test-file or a patch to an
existing test-file that illustrates the bug or desired feature.
CONTRIBUTORS¶
- •
- David Steinbrunner <dsteinbrunner@pobox.com>
- •
- Slaven Rezic <slaven@rezic.de>
- •
- Steve Throckmorton <arrestee@gmail.com>
- •
- Tim <oylenshpeegul@gmail.com>
AUTHORS¶
- •
- Jeff Pinyan <japhy.734+CPAN@gmail.com>
- •
- Caleb Cushing <xenoterracide@gmail.com>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2013 by Caleb Cushing and Jeff Pinyan.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.