.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "lsMode 3pm"
.TH lsMode 3pm "2021-01-06" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Stat::lsMode \- format file modes like the "ls \-l" command does
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Stat::lsMode;
\&
\&  $mode = (stat $file)[2];
\&  $permissions = format_mode($mode);
\&  # $permissions is now something like  \`drwxr\-xr\-x\*(Aq
\&
\&  $permissions = file_mode($file);   # Same as above
\&
\&  $permissions = format_perms(0644); # Produces just \*(Aqrw\-r\-\-r\-\-\*(Aq
\&
\&  $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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Stat::lsMode\*(C'\fR generates mode and permission strings that look like
the ones generated by the Unix \f(CW\*(C`ls \-l\*(C'\fR command.  For example, a
regular file that is readable by everyone and writable only by its
owner has the mode string \f(CW\*(C`\-rw\-r\-\-r\-\-\*(C'\fR.  \f(CW\*(C`Stat::lsMode\*(C'\fR 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 \f(CW\*(C`stat\*(C'\fR call.
.ie n .SS """format_mode"""
.el .SS "\f(CWformat_mode\fP"
.IX Subsection "format_mode"
Given a mode number (such as the third element of the list returned by
\&\f(CW\*(C`stat\*(C'\fR), return the appopriate ten-character mode string as it would
have been generated by \f(CW\*(C`ls \-l\*(C'\fR.  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, \f(CW\*(C`format_mode\*(C'\fR will return the string
\&\f(CW\*(C`drwxr\-xr\-x\*(C'\fR.
.PP
If \f(CW\*(C`format_mode\*(C'\fR is passed a permission number like \f(CW0755\fR, it will
return a nine-character string insted, with no leading character to
say what the file type is.  For example, \f(CW\*(C`format_mode(0755)\*(C'\fR will
return just \f(CW\*(C`rwxr\-xr\-x\*(C'\fR, without the leading \f(CW\*(C`d\*(C'\fR.
.ie n .SS """file_mode"""
.el .SS "\f(CWfile_mode\fP"
.IX Subsection "file_mode"
Given a filename, do \f(CW\*(C`lstat\*(C'\fR on the file to determine the mode, and
return the mode, formatted as above.
.SS "Novice Operation Mode"
.IX Subsection "Novice Operation Mode"
A common mistake when dealing with permission modes is to use \f(CW644\fR
where you meant to use \f(CW0644\fR.  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
\&\f(CW\*(C`\-w\-\-\-\-r\-T\*(C'\fR, not to \f(CW\*(C`rw\-r\-\-r\-\-\*(C'\fR.
.PP
The appearance of the bizarre permission \f(CW\*(C`\-w\-\-\-\-r\-T\*(C'\fR in a program is
almost a sure sign that someone used \f(CW644\fR when they meant to use
\&\f(CW0644\fR.  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
.PP
.Vb 1
\& Stat::lsMode\->novice(0);   # disable novice mode
\&
\& Stat::lsMode\->novice(1);   # enable novice mode again
.Ve
.PP
The surprising permissions that are diagnosed by this mode are:
.PP
.Vb 10
\&        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
.Ve
.PP
Of these, only 400 is remotely plausible.
.SH "BUGS"
.IX Header "BUGS"
As far as I know, the precise definition of the mode bits is portable
between varieties of Unix.  The module should, however, examine
\&\f(CW\*(C`stat.h\*(C'\fR or use some other method to find out if there are any local
variations, because Unix being Unix, someone somewhere probably does
it differently.
.PP
Maybe it \f(CW\*(C`file_mode\*(C'\fR 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 \f(CW\*(C`ls \-Ll\*(C'\fR does.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\(bu" 4
\&\f(CW\*(C`http://www.plover.com/~mjd/perl/lsMode/\*(C'\fR.
.IP "\(bu" 4
ls
.IP "\(bu" 4
chmod
.IP "\(bu" 4
stat
.SH "AUTHOR"
.IX Header "AUTHOR"
Mark-Jason Dominus (\f(CW\*(C`mjd\-perl\-lsmode@plover.com\*(C'\fR).