NAME

       Stat::lsMode - format file modes like the "ls -l" command does

SYNOPSIS

         use Stat::lsMode;

         $mode = (stat $file)[2];
         $permissions = format_mode($mode);
         # $permissions is now something like  `drwxr-xr-x'

         $permissions = file_mode($file);   # Same as above

         $permissions = format_perms(0644); # Produces just 'rw-r--r--'

         $permissions = format_perms(644);  # This generates a warning message:
         # mode 644 is very surprising.  Perhaps you meant 0644...

         Stat::lsMode->novice(0);           # Disable warning messages

DESCRIPTION

       "Stat::lsMode" generates mode and permission strings that look like the ones generated by
       the Unix "ls -l" command.  For example, a regular file that is readable by everyone and
       writable only by its owner has the mode string "-rw-r--r--".  "Stat::lsMode" will either
       examine the file and produce the right mode string for you, or you can pass it the mode
       that you get back from Perl's "stat" call.

   "format_mode"
       Given a mode number (such as the third element of the list returned by "stat"), return the
       appopriate ten-character mode string as it would have been generated by "ls -l".  For
       example, consider a directory that is readable and searchable by everyone, and also
       writable by its owner.  Such a directory will have mode 040755.  When passed this value,
       "format_mode" will return the string "drwxr-xr-x".

       If "format_mode" is passed a permission number like 0755, it will return a nine-character
       string insted, with no leading character to say what the file type is.  For example,
       "format_mode(0755)" will return just "rwxr-xr-x", without the leading "d".

   "file_mode"
       Given a filename, do "lstat" on the file to determine the mode, and return the mode,
       formatted as above.

   Novice Operation Mode
       A common mistake when dealing with permission modes is to use 644 where you meant to use
       0644.  Every permission has a numeric representation, but the representation only makes
       sense when you write the number in octal.  The decimal number 644 corresponds to a
       permission setting, but not the one you think.  If you write it in octal you get 01204,
       which corresponds to the unlikely permissions "-w----r-T", not to "rw-r--r--".

       The appearance of the bizarre permission "-w----r-T" in a program is almost a sure sign
       that someone used 644 when they meant to use 0644.  By default, this module will detect
       the use of such unlikely permissions and issue a warning if you try to format them.  To
       disable these warnings, use

        Stat::lsMode->novice(0);   # disable novice mode

        Stat::lsMode->novice(1);   # enable novice mode again

       The surprising permissions that are diagnosed by this mode are:

               111 => --xr-xrwx
               400 => rw--w----
               440 => rw-rwx---
               444 => rw-rwxr--
               551 => ---r--rwt
               600 => --x-wx--T
               640 => -w------T
               644 => -w----r-T
               660 => -w--w-r-T
               664 => -w--wx--T
               666 => -w--wx-wT
               700 => -w-rwxr-T
               711 => -wx---rwt
               750 => -wxr-xrwT
               751 => -wxr-xrwt
               751 => -wxr-xrwt
               755 => -wxrw--wt
               770 => r------wT
               771 => r------wt
               775 => r-----rwt
               777 => r----x--t

       Of these, only 400 is remotely plausible.

BUGS

       As far as I know, the precise definition of the mode bits is portable between varieties of
       Unix.  The module should, however, examine "stat.h" or use some other method to find out
       if there are any local variations, because Unix being Unix, someone somewhere probably
       does it differently.

       Maybe it "file_mode" should have an option that says that if the file is a symlink, to
       format the mode of the pointed to file instead of the mode of the link itself, the way "ls
       -Ll" does.

SEE ALSO

       •   "http://www.plover.com/~mjd/perl/lsMode/".

       •   ls

       •   chmod

       •   stat

AUTHOR

       Mark-Jason Dominus ("mjd-perl-lsmode@plover.com").