.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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" '' . ds C` . ds C' '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. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" 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 "File::chmod 3pm" .TH File::chmod 3pm "2015-02-14" "perl v5.20.2" "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" version 0.42 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 9 \& use File::chmod; \& $File::chmod::UMASK = 0; \& # It is recommended that you explicitly set $File::chmod::UMASK \& # as the default will change in the future \& # \& # 0 is recommended to behave like system chmod \& # 1 if you want File::chmod to apply your environment set umask. \& # 2 is how we detect that it\*(Aqs internally set, undef will become the \& # default in the future, eventually a lexicaly scoped API may be designed \& \& # 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 An added feature to version 0.30 is the \f(CW$UMASK\fR variable, explained in detail below; if \f(CW\*(C`symchmod()\*(C'\fR is called and this variable is true, then the function uses the (also new) \f(CW$MASK\fR variable (which defaults to \f(CW\*(C`umask()\*(C'\fR) 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 \s-1UNIX \s0\f(CW\*(C`chmod\*(C'\fR. \&\fBThis may change in the future.\fR .PP Symbolic modes are thoroughly described in your \fIchmod\fR\|(1) man page, but here are a few examples. .PP .Vb 2 \& 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. .SH "FUNCTIONS \- EXPORT" .IX Header "FUNCTIONS - EXPORT" .SS "chmod(\s-1MODE,FILES\s0)" .IX Subsection "chmod(MODE,FILES)" Takes an octal, symbolic, or \*(L"ls\*(R" mode, and then chmods each file appropriately. .SS "getchmod(\s-1MODE,FILES\s0)" .IX Subsection "getchmod(MODE,FILES)" Returns a list of modified permissions, without chmodding files. Accepts any of the three kinds of modes. .PP .Vb 3 \& @newmodes = getchmod("+x","file1","file2"); \& # @newmodes holds the octal permissions of the files\*(Aq \& # modes, if they were to be sent through chmod("+x"...) .Ve .SH "FUNCTIONS \- EXPORT_OK" .IX Header "FUNCTIONS - EXPORT_OK" .SS "symchmod(\s-1MODE,FILES\s0)" .IX Subsection "symchmod(MODE,FILES)" Takes a symbolic permissions mode, and chmods each file. .SS "lschmod(\s-1MODE,FILES\s0)" .IX Subsection "lschmod(MODE,FILES)" Takes an \*(L"ls\*(R" permissions mode, and chmods each file. .SS "getsymchmod(\s-1MODE,FILES\s0)" .IX Subsection "getsymchmod(MODE,FILES)" Returns a list of modified permissions, without chmodding files. Accepts only symbolic permission modes. .SS "getlschmod(\s-1MODE,FILES\s0)" .IX Subsection "getlschmod(MODE,FILES)" Returns a list of modified permissions, without chmodding files. Accepts only \*(L"ls\*(R" permission modes. .SS "getmod(\s-1FILES\s0)" .IX Subsection "getmod(FILES)" Returns a list of the current mode of each file. .SH "VARIABLES" .IX Header "VARIABLES" .ie n .SS "$File::chmod::DEBUG" .el .SS "\f(CW$File::chmod::DEBUG\fP" .IX Subsection "$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 .SS "$File::chmod::MASK" .el .SS "\f(CW$File::chmod::MASK\fP" .IX Subsection "$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 .SS "$File::chmod::UMASK" .el .SS "\f(CW$File::chmod::UMASK\fP" .IX Subsection "$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 "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 OS\s0" 4 .IX Item "RISC OS" Only good for changing \*(L"owner\*(R" and \*(L"other\*(R" read-write access. .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 "BUGS" .IX Header "BUGS" Please report any bugs or feature requests on the bugtracker website https://github.com/xenoterracide/file\-chmod/issues .PP 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. .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 David Steinbrunner .IP "\(bu" 4 Slaven Rezic .IP "\(bu" 4 Steve Throckmorton .IP "\(bu" 4 Tim .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Jeff Pinyan .IP "\(bu" 4 Caleb Cushing .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2015 by Caleb Cushing and Jeff Pinyan. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.