.\" Automatically generated by Pod::Man 2.18 (Pod::Simple 3.05) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "chmod 3pm" .TH chmod 3pm "2007-07-28" "perl v5.10.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::chmod \- Implements symbolic and ls chmod modes .SH "VERSION" .IX Header "VERSION" This is File::chmod v0.32. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use File::chmod; \& \& # 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 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" File::chmod is a utility that allows you to bypass system calls or bit processing of a file's permissions. It overloads the \fIchmod()\fR function with its own that gets an octal mode, a symbolic mode (see below), or an \*(L"ls\*(R" mode (see below). If you wish not to overload \fIchmod()\fR, you can export \fIsymchmod()\fR and \fIlschmod()\fR, which take, respectively, a symbolic mode and an \*(L"ls\*(R" mode. .PP Symbolic modes are thoroughly described in your \fIchmod\fR\|(1) man page, but here are a few examples. .PP .Vb 1 \& # NEW: if $UMASK is true, symchmod() applies a bit\-mask found in $MASK \& \& 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 \*(Aqother\*(Aq permissions, and the write bit for \*(Aqgroup\*(Aq \& \& chmod("=u","file1","file2"); \& # sets all bits to those in \*(Aquser\*(Aq .Ve .PP \&\*(L"ls\*(R" modes are the type produced on the left-hand side of an \f(CW\*(C`ls \-l\*(C'\fR on a directory. Examples are: .PP .Vb 3 \& 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 .Ve .PP The regular \fIchmod()\fR and \fIlschmod()\fR 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. \fIsymchmod()\fR 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. .PP An added feature to version 0.30 is the \f(CW$UMASK\fR variable, explained below; if \&\fIsymchmod()\fR is called and this variable is true, then the function uses the (also new) \f(CW$MASK\fR variable (which defaults to \fIumask()\fR) as a mask against the new mode. This is documented below more clearly. .SS "Functions" .IX Subsection "Functions" Exported by default: .IP "chmod(\s-1MODE\s0,FILES)" 4 .IX Item "chmod(MODE,FILES)" Takes an octal, symbolic, or \*(L"ls\*(R" mode, and then chmods each file appropriately. .IP "getchmod(\s-1MODE\s0,FILES)" 4 .IX Item "getchmod(MODE,FILES)" Returns a list of modified permissions, without chmodding files. Accepts any of the three kinds of modes. .Sp .Vb 3 \& @newmodes = getchmod("+x","file1","file2"); \& # @newmodes holds the octal permissons of the files\*(Aq \& # modes, if they were to be sent through chmod("+x"...) .Ve .PP Exported by request: .IP "symchmod(\s-1MODE\s0,FILES)" 4 .IX Item "symchmod(MODE,FILES)" Takes a symbolic permissions mode, and chmods each file. .IP "lschmod(\s-1MODE\s0,FILES)" 4 .IX Item "lschmod(MODE,FILES)" Takes an \*(L"ls\*(R" permissions mode, and chmods each file. .IP "getsymchmod(\s-1MODE\s0,FILES)" 4 .IX Item "getsymchmod(MODE,FILES)" Returns a list of modified permissions, without chmodding files. Accepts only symbolic permisson modes. .IP "getlschmod(\s-1MODE\s0,FILES)" 4 .IX Item "getlschmod(MODE,FILES)" Returns a list of modified permissions, without chmodding files. Accepts only \*(L"ls\*(R" permisson modes. .IP "getmod(\s-1FILES\s0)" 4 .IX Item "getmod(FILES)" Returns a list of the current mode of each file. .SS "Variables" .IX Subsection "Variables" .ie n .IP "$File::chmod::DEBUG" 4 .el .IP "\f(CW$File::chmod::DEBUG\fR" 4 .IX Item "$File::chmod::DEBUG" If set to a true value, it will report warnings, similar to those produced by \fIchmod()\fR 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 \f(CW$File::chmod::DEBUG\fR is true, the function will report an error. If not, you are not warned of the conflict. It is set to 1 as default. .ie n .IP "$File::chmod::MASK" 4 .el .IP "\f(CW$File::chmod::MASK\fR" 4 .IX Item "$File::chmod::MASK" Contains the umask to apply to new file modes when using \fIgetsymchmod()\fR. This defaults to the return value of \fIumask()\fR at compile time. Is only applied if \&\f(CW$UMASK\fR is true. .ie n .IP "$File::chmod::UMASK" 4 .el .IP "\f(CW$File::chmod::UMASK\fR" 4 .IX Item "$File::chmod::UMASK" This is a boolean which tells \fIgetsymchmod()\fR whether or not to apply the umask found in \f(CW$MASK\fR. It defaults to true. .SH "REVISIONS" .IX Header "REVISIONS" \&\fINote: this section was started with version 0.30.\fR .PP This is an in-depth look at the changes being made from version to version. .SS "0.31 to 0.32" .IX Subsection "0.31 to 0.32" .IP "\fBlicense added\fR" 4 .IX Item "license added" I added a license to this module so that it can be used places without asking my permission. Sorry, Adam. .SS "0.30 to 0.31" .IX Subsection "0.30 to 0.31" .IP "\fBfixed \f(BIgetsymchmod()\fB bug\fR" 4 .IX Item "fixed getsymchmod() bug" Whoa. \fIgetsymchmod()\fR was doing some crazy ish. That's about all I can say. I did a great deal of debugging, and fixed it up. It \s-1ALL\s0 had to do with two things: .Sp .Vb 1 \& $or = (/+=/ ? 1 : 0); # should have been /[+=]/ \& \& /u/ && $ok ? u_or() : u_not(); # should have been /u/ and $ok .Ve .IP "\fBfixed \f(BIgetmod()\fB bug\fR" 4 .IX Item "fixed getmod() bug" I was using \fImap()\fR incorrectly in \fIgetmod()\fR. Fixed that. .IP "\fBcondensed \f(BIlschmod()\fB\fR" 4 .IX Item "condensed lschmod()" I shorted it up, getting rid a variable. .SS "0.21 to 0.30" .IX Subsection "0.21 to 0.30" .IP "\fBadded \f(BIumask()\fB honoring for \f(BIsymchmod()\fB\fR" 4 .IX Item "added umask() honoring for symchmod()" The \fIsymchmod()\fR function now honors the \f(CW$UMASK\fR and \f(CW$MASK\fR variables. \f(CW$UMASK\fR is a boolean which indicates whether or not to honor the \f(CW$MASK\fR variable. \f(CW$MASK\fR holds a umask, and it defaults to \fIumask()\fR. \f(CW$UMASK\fR defaults to true. These variables are \s-1NOT\s0 exported. They must explictly set (i.e. \f(CW$File::chmod::UMASK\fR = 0). .IP "\fBfunction name changes\fR" 4 .IX Item "function name changes" Renamed internal function \fIdetermine_mode()\fR to \fImode()\fR. However, if you happen to be using \fIdetermine_mode()\fR somewhere, \fImode()\fR will be called, but you'll also get a warning about deprecation. .Sp Renamed internal functions {or,not}_{l,s,t} to {l,s,t}_{or,not}. This is to keep in standard with the \s-1OTHER\s0 6 pairs of bitwise functions, such as \fIr_or()\fR and \fIg_not()\fR. I don't know \s-1WHY\s0 the others had 'not' or 'or' in the front. .IP "\fBfixed debugging bugs\fR" 4 .IX Item "fixed debugging bugs" Certain calls to \fIwarn()\fR were not guarded by the \f(CW$DEBUG\fR variable, and now they are. Also, for some reason, I left a debugging check (that didn't check to see if \f(CW$DEBUG\fR was true) in \fIgetsymchmod()\fR, line 118. It printed \*(L"\s-1ENTERING\s0 /g/\*(R". It's gone now. .IP "\fBfixed set-uid and set-gid bug\fR" 4 .IX Item "fixed set-uid and set-gid bug" Heh, it seems that in the previous version of File::chmod, the following code went along broken: .Sp .Vb 4 \& # or_s sub, File/chmod.pm, v0.21, line 330 \& ($VAL & 00100) && do { \& $DEBUG && warn("execute bit must be on for set\-uid"); 1; \& } && next; .Ve .Sp Aside from me using '&&' more than enough (changed in the new code), this is broken. This is now fixed. .IP "\fBfixed file lock/set\-gid bug\fR" 4 .IX Item "fixed file lock/set-gid bug" The \fInot_l()\fR function (now renamed to \fIl_not()\fR) used to take the file mode and bit-wise \s-1NOT\s0 it with ~02000. However, it did not check if the file was locked vs. set-gid. Now, the function is \f(CW\*(C`$VAL &= ~02000 if not $VAL & 00010;\*(C'\fR. .IP "\fBremoved useless data structures\fR" 4 .IX Item "removed useless data structures" I do not know why I had the \f(CW$S\fR variable, or \f(CW%r\fR, \f(CW%w\fR, and \f(CW%x\fR hashes. In fact, \&\f(CW$S\fR was declared in \f(CW\*(C`use vars qw( ... );\*(C'\fR, but never given a value, and the \&\f(CW%r\fR, \f(CW%w\fR, and \f(CW%x\fR hashes had a 'full' key which never got used. And the hashes themselves weren't really needed anyway. Here is a list of the variables no longer in use, and what they have been replaced with (if any): .Sp .Vb 5 \& $S nothing \& $U, $G, $O $W \& %r, %w, %x octal numbers \& @files @_ (I had @files = @_; in nearly EVERY sub) \& $c $_ .Ve .IP "\fBcompacted code\fR" 4 .IX Item "compacted code" The first version of File::chmod that was published was 0.13, and it was written in approximately 10 days, being given the off-and-on treatment I end up having to give several projects, due to more pressing matters. Well, since then, most of the code has stayed the same, although bugs were worked out. Well, I got rid of a lot of slow, clunky, and redundant sections of code in this version. Sections include the processing of each character of the mode in \fIgetsymchmod()\fR, the \fIgetmod()\fR subroutine, um, nearly \s-1ALL\s0 of the \fIgetsymchmod()\fR function, now that I look at it. .Sp Here's part of the \fIgetsymchmod()\fR rewrite: .Sp .Vb 7 \& for ($c){ \& if (/u/){ \& u_or() if $MODE eq "+" or $MODE eq "="; \& u_not() if $MODE eq "\-"; \& } \& ... \& } \& \& # changed to \& \& /u/ && $or ? u_or() : u_and(); \& # note: operating on $_, $c isn\*(Aqt used anymore \& # note: $or holds 1 if the $MODE was + or =, 0 if $MODE was \- \& # note: previous was redundant. didn\*(Aqt need $MODE eq "\-" check \& # because u_or() and u_not() both go to the next character .Ve .SH "PORTING" .IX Header "PORTING" This is only good on Unix-like boxes. I would like people to help me work on File::chmod for any \s-1OS\s0 that deserves it. If you would like to help, please email me (address below) with the \s-1OS\s0 and any information you might have on how \&\fIchmod()\fR 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 \*(L"perlport\*(R"): .IP "Win32" 4 .IX Item "Win32" Only good for changing \*(L"owner\*(R" read-write access, \*(L"group\*(R", and \*(L"other\*(R" bits are meaningless. \fI\s-1NOTE:\s0 Win32::File and Win32::FileSecurity already do this. I do not currently see a need to port File::chmod.\fR .IP "MacOS" 4 .IX Item "MacOS" Only limited meaning. Disabling/enabling write permission is mapped to locking/unlocking the file. .IP "\s-1RISC\s0 \s-1OS\s0" 4 .IX Item "RISC OS" Only good for changing \*(L"owner\*(R" and \*(L"other\*(R" read-write access. .SH "AUTHOR" .IX Header "AUTHOR" Jeff \f(CW\*(C`japhy\*(C'\fR Pinyan, \fIjaphy.734+CPAN@gmail.com\fR, \s-1CPAN\s0 \s-1ID:\s0 \s-1PINYAN\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" .Vb 4 \& Stat::lsMode (by Mark\-James Dominus, CPAN ID: MJD) \& chmod(1) manpage \& perldoc \-f chmod \& perldoc \-f stat .Ve .SH "COPYRIGHT AND LICENCE" .IX Header "COPYRIGHT AND LICENCE" Copyright (C) 2007 by Jeff Pinyan .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.