GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  FILE::CHMOD (3)

.ds Aq ’

NAME

File::chmod - Implements symbolic and ls chmod modes

CONTENTS

VERSION

This is File::chmod v0.32.

SYNOPSIS



  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



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.

Symbolic modes are thoroughly described in your chmod(1) man page, but here are a few examples.



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

An added feature to version 0.30 is the $UMASK variable, explained 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 is documented below more clearly.

    Functions

Exported by default:
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 permissons of the files
  # modes, if they were to be sent through chmod("+x"...)



Exported by request:
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 permisson modes.
getlschmod(MODE,FILES) Returns a list of modified permissions, without chmodding files. Accepts only ls permisson 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.

REVISIONS

Note: this section was started with version 0.30.

This is an in-depth look at the changes being made from version to version.

    0.31 to 0.32

<B>license addedB> I added a license to this module so that it can be used places without asking my permission. Sorry, Adam.

    0.30 to 0.31

<B>fixed B>getsymchmod()<B> bugB> Whoa. getsymchmod() was doing some crazy ish. That’s about all I can say. I did a great deal of debugging, and fixed it up. It ALL had to do with two things:



  $or = (/+=/ ? 1 : 0); # should have been /[+=]/

  /u/ && $ok ? u_or() : u_not(); # should have been /u/ and $ok



<B>fixed B>getmod()<B> bugB> I was using map() incorrectly in getmod(). Fixed that.
<B>condensed B>lschmod()<B>B> I shorted it up, getting rid a variable.

    0.21 to 0.30

<B>added B>umask()<B> honoring for B>symchmod()<B>B> The symchmod() function now honors the $UMASK and $MASK variables. $UMASK is a boolean which indicates whether or not to honor the $MASK variable. $MASK holds a umask, and it defaults to umask(). $UMASK defaults to true. These variables are NOT exported. They must explictly set (i.e. $File::chmod::UMASK = 0).
<B>function name changesB> Renamed internal function determine_mode() to mode(). However, if you happen to be using determine_mode() somewhere, mode() will be called, but you’ll also get a warning about deprecation.

Renamed internal functions {or,not}_{l,s,t} to {l,s,t}_{or,not}. This is to keep in standard with the OTHER 6 pairs of bitwise functions, such as r_or() and g_not(). I don’t know WHY the others had ’not’ or ’or’ in the front.

<B>fixed debugging bugsB> Certain calls to warn() were not guarded by the $DEBUG variable, and now they are. Also, for some reason, I left a debugging check (that didn’t check to see if $DEBUG was true) in getsymchmod(), line 118. It printed ENTERING /g/. It’s gone now.
<B>fixed set-uid and set-gid bugB> Heh, it seems that in the previous version of File::chmod, the following code went along broken:



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



Aside from me using ’&&’ more than enough (changed in the new code), this is broken. This is now fixed.

<B>fixed file lock/set-gid bugB> The not_l() function (now renamed to l_not()) used to take the file mode and bit-wise NOT it with ~02000. However, it did not check if the file was locked vs. set-gid. Now, the function is $VAL &= ~02000 if not $VAL & 00010;.
<B>removed useless data structuresB> I do not know why I had the $S variable, or %r, %w, and %x hashes. In fact, $S was declared in use vars qw( ... );, but never given a value, and the %r, %w, and %x 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):



  $S            nothing
  $U, $G, $O    $W
  %r, %w, %x    octal numbers
  @files        @_ (I had @files = @_; in nearly EVERY sub)
  $c            $_



<B>compacted codeB> 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 getsymchmod(), the getmod() subroutine, um, nearly ALL of the getsymchmod() function, now that I look at it.

Here’s part of the getsymchmod() rewrite:



  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 isnt used anymore
  # note: $or holds 1 if the $MODE was + or =, 0 if $MODE was -
  # note: previous was redundant.  didnt need $MODE eq "-" check
  #       because u_or() and u_not() both go to the next character



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.

AUTHOR

Jeff japhy Pinyan, japhy.734+CPAN@gmail.com, CPAN ID: PINYAN

SEE ALSO



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



COPYRIGHT AND LICENCE

Copyright (C) 2007 by Jeff Pinyan

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 CHMOD (3) 2007-07-28

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.