== INFORMATION ==

This module allows for symbolic (i.e. +rx-w) file permissions as well as "ls"
modes (i.e. -r-xr-xr-x).

This is File::chmod v0.30.

PLEASE read the POD, there have been several changes since the last
version.  Nothing that will wreck your programs, but things that you
should be aware of.

To learn more, go to http://www.pobox.com/japhy/perl.
Jeff Pinyan, japhy+perl@pobox.com, CPAN ID: PINYAN.


== INSTALLATION INSTRUCTIONS ==

Unpack the .tar.gz file.

Run:
        perl Makefile.PL
        make
        make test
        make install


== MANUAL ==

NAME
    File::chmod - Implements symbolic and ls chmod modes

VERSION
    This is File::chmod v0.30.

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 carpings, 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 carped 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.21 to 0.30

    added umask() honoring for symchmod()
        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).

    function name changes
        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.

    fixed debugging bugs
        Certain calls to carp() 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.

    fixed set-uid and set-gid bug
        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 && carp("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.

    fixed file lock/set-gid bug
        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;'.

    removed useless data structures
        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            $_

    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
        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 isn't used anymore
          # note: $or holds 1 if the $MODE was + or =, 0 if $MODE was -
          # note: previous was redundant.  didn't 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 the perlport entry elsewhere in this document
    ):

    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 Pinyan, japhy+perl@pobox.com, CPAN ID: PINYAN

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

