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

VERSION
    version 0.34

SYNOPSIS
      use File::chmod;
      # It is recommended that you explicitly set $UMASK as the default may change
      # in the future, 0 is recommended to behave like system chmod, set to 1 if
      # you want it enabled, so that if later we decide to disable it by default
      # it won't change your code. $UMASK has been changed to be true by using
      # numeric value 2 internally
      $File::chmod::UMASK = 0;

      # 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 one by default,
    and changes the behavior from what you would expect if you are used to
    UNIX "chmod". This may change in the future.

    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
    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
    license added
        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
    fixed getsymchmod() bug
        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

    fixed getmod() bug
        I was using map() incorrectly in getmod(). Fixed that.

    condensed lschmod()
        I shorted it up, getting rid a variable.

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

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

    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 "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

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.

