Stat::lsMode(3pm)

Usage

  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

Overview

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

Interface

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

Copyright and license

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

Releases

10 releases since Debian 4.0 (Etch); the text changed 5 times.