---
name: "Stat::lsMode"
section: "3pm"
platform: "linux"
package: "libstat-lsmode-perl"
version: "0.51-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Stat::lsMode"
---

# Stat::lsMode(3pm)

format file modes like the "ls -l" command does

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

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

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

## AUTHOR

Mark-Jason Dominus

## COPYRIGHT AND LICENSE

This software is copyright (c) 1998 by Mark-Jason Dominus.

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