path: root/man-pages-posix-2017/man1p/ls.1p

'\" et
.TH LS "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
ls
\(em list directory contents
.SH SYNOPSIS
.LP
.nf
ls \fB[\fR-ikqrs\fB] [\fR-g\|lno\|\fB] [\fR-A|-a\fB] [\fR-C|-m|-x|-1\fB]\fR \e
    \fB[\fR-F|-p\fB] [\fR-H|-L\fB] [\fR-R|-d\fB] [\fR-S|-f|-t\fB] [\fR-c|-u\fB] [\fIfile\fR...\fB]\fR
.fi
.SH DESCRIPTION
For each operand that names a file of a type other than directory or
symbolic link to a directory,
.IR ls
shall write the name of the file as well as any requested, associated
information. For each operand that names a file of type directory,
.IR ls
shall write the names of files contained within the directory as well
as any requested, associated information. Filenames beginning
with a
<period>
(\c
.BR '.' )
and any associated information shall not be written out unless
explicitly referenced, the
.BR \-A
or
.BR \-a
option is supplied, or an implementation-defined condition causes them
to be written. If one or more of the
.BR \-d ,
.BR \-F ,
or
.BR \-l
options are specified, and neither the
.BR \-H
nor the
.BR \-L
option is specified, for each operand that names a file of type
symbolic link to a directory,
.IR ls
shall write the name of the file as well as any requested, associated
information. If none of the
.BR \-d ,
.BR \-F ,
or
.BR \-l
options are specified, or the
.BR \-H
or
.BR \-L
options are specified, for each operand that names a file of type
symbolic link to a directory,
.IR ls
shall write the names of files contained within the directory as well
as any requested, associated information. In each case where the names
of files contained within a directory are written, if the directory
contains any symbolic links then
.IR ls
shall evaluate the file information and file type to be those of
the symbolic link itself, unless the
.BR \-L
option is specified.
.P
If no operands are specified,
.IR ls
shall behave as if a single operand of dot (\c
.BR '.' )
had been specified. If more than one operand is specified,
.IR ls
shall write non-directory operands first; it shall sort directory and
non-directory operands separately according to the collating sequence
in the current locale.
.P
Whenever
.IR ls
sorts filenames or pathnames according to the collating sequence in
the current locale, if this collating sequence does not have a total
ordering of all characters (see the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 7.3.2" ", " "LC_COLLATE"),
then any filenames or pathnames that collate equally should be further
compared byte-by-byte using the collating sequence for the POSIX locale.
.P
The
.IR ls
utility shall detect infinite loops; that is, entering a previously
visited directory that is an ancestor of the last file encountered.
When it detects an infinite loop,
.IR ls
shall write a diagnostic message to standard error and shall either
recover its position in the hierarchy or terminate.
.SH OPTIONS
The
.IR ls
utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
.P
The following options shall be supported:
.IP "\fB\-A\fP" 10
Write out all directory entries, including those whose names begin with a
<period>
(\c
.BR '.' )
but excluding the entries dot and dot-dot (if they exist).
.IP "\fB\-C\fP" 10
Write multi-text-column output with entries sorted down the columns,
according to the collating sequence. The number of text columns and the
column separator characters are unspecified, but should be adapted to
the nature of the output device. This option disables long format output.
.IP "\fB\-F\fP" 10
Do not follow symbolic links named as operands unless the
.BR \-H
or
.BR \-L
options are specified. Write a
<slash>
(\c
.BR '/' )
immediately after each pathname that is a directory, an
<asterisk>
(\c
.BR '*' )
after each that is executable, a
<vertical-line>
(\c
.BR '|' )
after each that is a FIFO, and an at-sign (\c
.BR '@' )
after each that is a symbolic link. For other file types, other
symbols may be written.
.IP "\fB\-H\fP" 10
Evaluate the file information and file type for symbolic links specified
on the command line to be those of the file referenced by the link,
and not the link itself; however,
.IR ls
shall write the name of the link itself and not the file referenced by
the link.
.IP "\fB\-L\fP" 10
Evaluate the file information and file type for all symbolic links
(whether named on the command line or encountered in a file hierarchy)
to be those of the file referenced by the link, and not the link
itself; however,
.IR ls
shall write the name of the link itself and not the file referenced by
the link. When
.BR \-L
is used with
.BR \-l ,
write the contents of symbolic links in the long format (see the STDOUT
section).
.IP "\fB\-R\fP" 10
Recursively list subdirectories encountered. When a symbolic link to a
directory is encountered, the directory shall not be recursively listed
unless the
.BR \-L
option is specified.
The use of
.BR \-R
with
.BR \-d
or
.BR \-f
produces unspecified results.
.IP "\fB\-S\fP" 10
Sort with the primary key being file size (in decreasing order) and the
secondary key being filename in the collating sequence (in increasing
order).
.IP "\fB\-a\fP" 10
Write out all directory entries, including those whose names begin with a
<period>
(\c
.BR '.' ).
.IP "\fB\-c\fP" 10
Use time of last modification of the file status information (see the Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<sys_stat.h>\fP")
instead of last modification of the file itself for sorting (\c
.BR \-t )
or writing (\c
.BR \-l ).
.IP "\fB\-d\fP" 10
Do not follow symbolic links named as operands unless the
.BR \-H
or
.BR \-L
options are specified. Do not treat directories differently than other
types of files. The use of
.BR \-d
with
.BR \-R
or
.BR \-f
produces unspecified results.
.IP "\fB\-f\fP" 10
List the entries in directory operands in the order they appear in the
directory. The behavior for non-directory operands is unspecified. This
option shall turn on
.BR \-a .
When
.BR \-f
is specified, any occurrences of the
.BR \-r ,
.BR \-S ,
and
.BR \-t
options shall be ignored and any occurrences of the
.BR \-A ,
.BR \-g ,
.BR \-l ,
.BR \-n ,
.BR \-o ,
and
.BR \-s
options may be ignored. The use of
.BR \-f
with
.BR \-R
or
.BR \-d
produces unspecified results.
.IP "\fB\-g\fP" 10
Turn on the
.BR \-l
(ell) option, but disable writing the file's owner name or number.
Disable the
.BR \-C ,
.BR \-m ,
and
.BR \-x
options.
.IP "\fB\-i\fP" 10
For each file, write the file's file serial number (see
\fIstat\fR()
in the System Interfaces volume of POSIX.1\(hy2017).
.IP "\fB\-k\fP" 10
Set the block size for the
.BR \-s
option and the per-directory block count written for the
.BR \-l ,
.BR \-n ,
.BR \-s ,
.BR \-g ,
and
.BR \-o
options (see the STDOUT section) to 1\|024 bytes.
.IP "\fB\-l\fP" 10
(The letter ell.) Do not follow symbolic links named as operands unless
the
.BR \-H
or
.BR \-L
options are specified. Write out in long format (see the STDOUT
section). Disable the
.BR \-C ,
.BR \-m ,
and
.BR \-x
options.
.IP "\fB\-m\fP" 10
Stream output format; list pathnames across the page, separated by a
<comma>
character followed by a
<space>
character. Use a
<newline>
character as the list terminator and after the separator sequence when
there is not room on a line for the next list entry. This option disables
long format output.
.IP "\fB\-n\fP" 10
Turn on the
.BR \-l
(ell) option, but when writing the file's owner or group, write
the file's numeric UID or GID rather than the user or group name,
respectively. Disable the
.BR \-C ,
.BR \-m ,
and
.BR \-x
options.
.IP "\fB\-o\fP" 10
Turn on the
.BR \-l
(ell) option, but disable writing the file's group name or number.
Disable the
.BR \-C ,
.BR \-m ,
and
.BR \-x
options.
.IP "\fB\-p\fP" 10
Write a
<slash>
(\c
.BR '/' )
after each filename if that file is a directory.
.IP "\fB\-q\fP" 10
Force each instance of non-printable filename characters and
<tab>
characters to be written as the
<question-mark>
(\c
.BR '?' )
character. Implementations may provide this option by default if the
output is to a terminal device.
.IP "\fB\-r\fP" 10
Reverse the order of the sort to get reverse collating sequence oldest
first, or smallest file size first depending on the other options
given.
.IP "\fB\-s\fP" 10
Indicate the total number of file system blocks consumed by each file
displayed. If the
.BR \-k
option is also specified, the block size shall be 1\|024 bytes;
otherwise, the block size is implementation-defined.
.IP "\fB\-t\fP" 10
Sort with the primary key being time modified (most recently modified
first) and the secondary key being filename in the collating sequence.
For a symbolic link, the time used as the sort key is that of the
symbolic link itself, unless
.IR ls
is evaluating its file information to be that of the file referenced
by the link (see the
.BR \-H
and
.BR \-L
options).
.IP "\fB\-u\fP" 10
Use time of last access (see the Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<sys_stat.h>\fP")
instead of last modification of the file for sorting (\c
.BR \-t )
or writing (\c
.BR \-l ).
.IP "\fB\-x\fP" 10
The same as
.BR \-C ,
except that the multi-text-column output is produced with entries sorted
across, rather than down, the columns. This option disables long format
output.
.IP "\fB\-1\fP" 10
(The numeric digit one.) Force output to be one entry per line.
This option does not disable long format output. (Long format output is
enabled by
.BR \-g ,
.BR \-l
(ell),
.BR \-n ,
and
.BR \-o ;
and disabled by
.BR \-C ,
.BR \-m ,
and
.BR \-x .)
.P
If an option that enables long format output (\c
.BR \-g ,
.BR \-l
(ell),
.BR \-n ,
and
.BR "\\-o\|\" )
is given with an option that disables long format output (\c
.BR \-C ,
.BR \-m ,
and
.BR \-x ),
this shall not be considered an error. The last of these options
specified shall determine whether long format output is written.
.P
If
.BR \-R ,
.BR \-d ,
or
.BR \-f
are specified, the results of specifying these mutually-exclusive options
are specified by the descriptions of these options above. If more
than one of any of the other options shown in the SYNOPSIS section in
mutually-exclusive sets are given, this shall not be considered an error;
the last option specified in each set shall determine the output.
.P
Note that if
.BR \-t
is specified,
.BR \-c
and
.BR \-u
are not only mutually-exclusive with each other, they are also
mutually-exclusive with
.BR \-S
when determining sort order. But even if
.BR \-S
is specified after all occurrences of
.BR \-c ,
.BR \-t ,
and
.BR \-u ,
the last use of
.BR \-c
or
.BR \-u
determines the timestamp printed when producing long format output.
.SH OPERANDS
The following operand shall be supported:
.IP "\fIfile\fR" 10
A pathname of a file to be written. If the file specified is not
found, a diagnostic message shall be output on standard error.
.SH STDIN
Not used.
.SH "INPUT FILES"
None.
.br
.SH "ENVIRONMENT VARIABLES"
The following environment variables shall affect the execution of
.IR ls :
.IP "\fICOLUMNS\fP" 10
Determine the user's preferred column position width for writing
multiple text-column output. If this variable contains a string
representing a decimal integer, the
.IR ls
utility shall calculate how many pathname text columns to write (see
.BR \-C )
based on the width provided. If
.IR COLUMNS
is not set or invalid, an implementation-defined number of column
positions shall be assumed, based on the implementation's knowledge of
the output device. The column width chosen to write the names of files
in any given directory shall be constant. Filenames shall not be
truncated to fit into the multiple text-column output.
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 8.2" ", " "Internationalization Variables"
for the precedence of internationalization variables used to determine
the values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_COLLATE\fP" 10
.br
Determine the locale for character collation information in determining
the pathname collation sequence.
.IP "\fILC_CTYPE\fP" 10
Determine the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to multi-byte
characters in arguments) and which characters are defined as printable
(character class
.BR print ).
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error.
.IP "\fILC_TIME\fP" 10
Determine the format and contents for date and time strings written by
.IR ls .
.IP "\fINLSPATH\fP" 10
Determine the location of message catalogs for the processing of
.IR LC_MESSAGES .
.IP "\fITZ\fP" 10
Determine the timezone for date and time strings written by
.IR ls .
If
.IR TZ
is unset or null, an unspecified default timezone shall be used.
.SH "ASYNCHRONOUS EVENTS"
Default.
.SH STDOUT
The default format shall be to list one entry per line to standard
output; the exceptions are to terminals or when one of the
.BR \-C ,
.BR \-m ,
or
.BR \-x
options is specified. If the output is to a terminal, the format is
implementation-defined.
.P
When
.BR \-m
is specified, the format used for the last element of the list
shall be:
.sp
.RS 4
.nf

"%s\en", <\fIfilename\fR>
.fi
.P
.RE
.P
The format used for each other element of the list shall be:
.sp
.RS 4
.nf

"%s,%s", <\fIfilename\fR>, <\fIseparator\fR>
.fi
.P
.RE
.P
where, if there is not room for the next element of the list to fit
within the current line length, <\fIseparator\fP> is a string containing
an optional
<space>
character and a mandatory
<newline>
character; otherwise it is a single
<space>
character.
.P
If the
.BR \-i
option is specified, the file's file serial number (see the Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<sys_stat.h>\fP")
shall be written in the following format before any other output for
the corresponding entry:
.sp
.RS 4
.nf

%u ", <\fIfile serial number\fR>
.fi
.P
.RE
.P
If the
.BR \-l
option is specified, the following information shall be written for
files other than character special and block special files:
.sp
.RS 4
.nf

"%s %u %s %s %u %s %s\en", <\fIfile mode\fR>, <\fInumber of links\fR>,
    <\fIowner name\fR>, <\fIgroup name\fR>, <\fIsize\fR>, <\fIdate and time\fR>,
    <\fIpathname\fR>
.fi
.P
.RE
.P
If the
.BR \-l
option is specified, the following information shall be written
for character special and block special files:
.sp
.RS 4
.nf

"%s %u %s %s %s %s %s\en", <\fIfile mode\fR>, <\fInumber of links\fR>,
    <\fIowner name\fR>, <\fIgroup name\fR>, <\fIdevice info\fR>, <\fIdate and time\fR>,
    <\fIpathname\fR>
.fi
.P
.RE
.P
In both cases if the file is a symbolic link and the
.BR \-L
option is also specified, this information shall be for the file
resolved from the symbolic link, except that the <\fIpathname\fP> field
shall contain the pathname of the symbolic link itself. If the file is
a symbolic link and the
.BR \-L
option is not specified, this information shall be about the link itself
and the <\fIpathname\fP> field shall be of the form:
.sp
.RS 4
.nf

"%s -> %s", <\fIpathname of link\fR>, <\fIcontents of link\fR>
.fi
.P
.RE
.P
The
.BR \-n ,
.BR \-g ,
and
.BR \-o
options use the same format as
.BR \-l ,
but with omitted items and their associated
<blank>
characters. See the OPTIONS section.
.P
In both the preceding
.BR \-l
forms, if <\fIowner name\fR> or <\fIgroup name\fR> cannot be
determined, or if
.BR \-n
is given, they shall be replaced with their associated numeric values
using the format
.BR %u .
.P
The <\fIsize\fP> field shall contain the value that would be returned
for the file in the
.IR st_size
field of
.BR "struct stat"
(see the Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<sys_stat.h>\fP").
Note that for some file types this value is unspecified.
.P
The <\fIdevice\ info\fP> field shall contain implementation-defined
information associated with the device in question.
.P
The <\fIdate\ and\ time\fP> field shall contain the appropriate date
and timestamp of when the file was last modified. In the POSIX locale,
the field shall be the equivalent of the output of the following
.IR date
command:
.sp
.RS 4
.nf

date "+%b %e %H:%M"
.fi
.P
.RE
.P
if the file has been modified in the last six months, or:
.sp
.RS 4
.nf

date "+%b %e %Y"
.fi
.P
.RE
.P
(where two
<space>
characters are used between
.BR %e
and
.BR %Y )
if the file has not been modified in the last six months or if the
modification date is in the future, except that, in both cases, the final
<newline>
produced by
.IR date
shall not be included and the output shall be as if the
.IR date
command were executed at the time of the last modification date of the
file rather than the current time. When the
.IR LC_TIME
locale category is not set to the POSIX locale, a different format and
order of presentation of this field may be used.
.P
If the pathname was specified as a
.IR file
operand, it shall be written as specified.
.P
The file mode written under the
.BR \-l ,
.BR \-n ,
.BR \-g ,
and
.BR \-o
options shall consist of the following format:
.sp
.RS 4
.nf

"%c%s%s%s%s", <\fIentry type\fR>, <\fIowner permissions\fR>,
    <\fIgroup permissions\fR>, <\fIother permissions\fR>,
    <\fIoptional alternate access method flag\fR>
.fi
.P
.RE
.P
The <\fIoptional\ alternate\ access\ method\ flag\fP> shall be the
empty string if there is no alternate or additional access control
method associated with the file; otherwise, it shall be a string
containing a single printable character that is not a
<blank>.
.P
The <\fIentry\ type\fP> character shall describe the type of file, as
follows:
.IP "\fRd\fP" 8
Directory.
.IP "\fRb\fP" 8
Block special file.
.IP "\fRc\fP" 8
Character special file.
.IP "\fRl\fP\ (ell)" 8
Symbolic link.
.IP "\fRp\fP" 8
FIFO.
.IP "\fR\-\fP" 8
Regular file.
.P
Implementations may add other characters to this list to represent
other implementation-defined file types.
.P
The next three fields shall be three characters each:
.IP "<\fIowner permissions\fP>" 6
.br
Permissions for the file owner class (see the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 4.5" ", " "File Access Permissions").
.IP "<\fIgroup permissions\fP>" 6
.br
Permissions for the file group class.
.IP "<\fIother permissions\fP>" 6
.br
Permissions for the file other class.
.P
Each field shall have three character positions:
.IP " 1." 4
If
.BR 'r' ,
the file is readable; if
.BR '\-' ,
the file is not readable.
.IP " 2." 4
If
.BR 'w' ,
the file is writable; if
.BR '\-' ,
the file is not writable.
.IP " 3." 4
The first of the following that applies:
.RS 4 
.IP "\fRS\fR" 6
If in <\fIowner\ permissions\fP>, the file is not executable and
set-user-ID mode is set. If in <\fIgroup\ permissions\fP>, the file is
not executable and set-group-ID mode is set.
.IP "\fRs\fR" 6
If in <\fIowner\ permissions\fP>, the file is executable and
set-user-ID mode is set. If in <\fIgroup\ permissions\fP>, the file is
executable and set-group-ID mode is set.
.IP "\fRT\fR" 6
If in <\fIother\ permissions\fP> and the file is a directory, search
permission is not granted to others, and the restricted deletion flag
is set.
.IP "\fRt\fR" 6
If in <\fIother\ permissions\fP> and the file is a directory, search
permission is granted to others, and the restricted deletion flag
is set.
.IP "\fRx\fR" 6
The file is executable or the directory is searchable.
.IP "\fR\-\fR" 6
None of the attributes of
.BR 'S' ,
.BR 's' ,
.BR 'T' ,
.BR 't' ,
or
.BR 'x' 
applies.
.P
Implementations may add other characters to this list for the third
character position. Such additions shall, however, be written in
lowercase if the file is executable or searchable, and in uppercase if
it is not.
.RE
.P
If any of the
.BR \-l ,
.BR \-n ,
.BR \-s ,
.BR \-g ,
or
.BR \-o
options is specified, each list of files within the directory shall be
preceded by a status line indicating the number of file system blocks
occupied by files in the directory in 512-byte units if the
.BR \-k
option is not specified, or 1\|024-byte units if the
.BR \-k
option is specified, rounded up to the next integral number of units,
if necessary. In the POSIX locale, the format shall be:
.sp
.RS 4
.nf

"total %u\en", <\fInumber of units in the directory\fR>
.fi
.P
.RE
.P
If more than one directory, or a combination of non-directory files and
directories are written, either as a result of specifying multiple
operands, or the
.BR \-R
option, each list of files within a directory shall be preceded by:
.sp
.RS 4
.nf

"\en%s:\en", <\fIdirectory name\fR>
.fi
.P
.RE
.P
If this string is the first thing to be written, the first
<newline>
shall not be written. This output shall precede the number of units in
the directory.
.P
If the
.BR \-s
option is given, each file shall be written with the number of blocks
used by the file. Along with
.BR \-C ,
.BR \-1 ,
.BR \-m ,
or
.BR \-x ,
the number and a
<space>
shall precede the filename; with
.BR \-l ,
.BR \-n ,
.BR \-g ,
or
.BR \-o ,
they shall precede each line describing a file.
.SH STDERR
The standard error shall be used only for diagnostic messages.
.SH "OUTPUT FILES"
None.
.SH "EXTENDED DESCRIPTION"
None.
.SH "EXIT STATUS"
The following exit values shall be returned:
.IP "\00" 6
Successful completion.
.IP >0 6
An error occurred.
.SH "CONSEQUENCES OF ERRORS"
Default.
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
Many implementations use the
<equals-sign>
(\c
.BR '=' )
to denote sockets bound to the file system for the
.BR \-F
option. Similarly, many historical implementations use the
.BR 's' 
character to denote sockets as the entry type characters for the
.BR \-l
option.
.P
It is difficult for an application to use every part of the file modes
field of
.IR ls
.BR \-l
in a portable manner. Certain file types and executable bits are not
guaranteed to be exactly as shown, as implementations may have
extensions. Applications can use this field to pass directly to a user
printout or prompt, but actions based on its contents should generally
be deferred, instead, to the
.IR test
utility.
.P
The output of
.IR ls
(with the
.BR \-l
and related options) contains information that logically could be used
by utilities such as
.IR chmod
and
.IR touch
to restore files to a known state. However, this information is
presented in a format that cannot be used directly by those utilities
or be easily translated into a format that can be used. A character
has been added to the end of the permissions string so that
applications at least have an indication that they may be working in an
area they do not understand instead of assuming that they can translate
the permissions string into something that can be used. Future versions
or related documents may define one or more specific characters to be
used based on different standard additional or alternative access
control mechanisms.
.P
As with many of the utilities that deal with filenames, the output of
.IR ls
for multiple files or in one of the long listing formats must be used
carefully on systems where filenames can contain embedded white
space. Systems and system administrators should institute policies and
user training to limit the use of such filenames.
.P
The number of disk blocks occupied by the file that it reports varies
depending on underlying file system type, block size units reported,
and the method of calculating the number of blocks. On some file
system types, the number is the actual number of blocks occupied by the
file (counting indirect blocks and ignoring holes in the file); on
others it is calculated based on the file size (usually making an
allowance for indirect blocks, but ignoring holes).
.SH EXAMPLES
An example of a small directory tree being fully listed with
.IR ls
.BR "\-laRF\ a"
in the POSIX locale:
.sp
.RS 4
.nf

total 11
drwxr-xr-x   3 fox      prog          64 Jul  4 12:07 ./
drwxrwxrwx   4 fox      prog        3264 Jul  4 12:09 ../
drwxr-xr-x   2 fox      prog          48 Jul  4 12:07 b/
-rwxr--r--   1 fox      prog         572 Jul  4 12:07 foo*
.P
a/b:
total 4
drwxr-xr-x   2 fox      prog          48 Jul  4 12:07 ./
drwxr-xr-x   3 fox      prog          64 Jul  4 12:07 ../
-rw-r--r--   1 fox      prog         700 Jul  4 12:07 bar
.fi
.P
.RE
.SH RATIONALE
Some historical implementations of the
.IR ls
utility show all entries in a directory except dot and dot-dot when a
superuser invokes
.IR ls
without specifying the
.BR \-a
option. When ``normal'' users invoke
.IR ls
without specifying
.BR \-a ,
they should not see information about any files with names beginning
with a
<period>
unless they were named as
.IR file
operands.
.P
Implementations are expected to traverse arbitrary depths when
processing the
.BR \-R
option. The only limitation on depth should be based on running out of
physical storage for keeping track of untraversed directories.
.P
The
.BR \-1
(one) option was historically found in BSD and BSD-derived
implementations only. It is required in this volume of POSIX.1\(hy2017 so that conforming
applications might ensure that output is one entry per line, even if
the output is to a terminal.
.P
The
.BR \-S
option was added in Issue 7, but had been provided by several
implementations for many years. The description given in the
standard documents historic practice, but does not match much of the
documentation that described its behavior. Historical documentation
typically described it as something like:
.IP "\fB\-S\fP" 10
Sort by size (largest size first) instead of by name. Special character
devices (listed last) are sorted by name.
.P
even though the file type was never considered when sorting the output.
Character special files do typically sort close to the end of the list
because their file size on most implementations is zero. But they are
sorted alphabetically with any other files that happen to have the same
file size (zero), not sorted separately and added to the end.
.P
This volume of POSIX.1\(hy2017 is frequently silent about what happens when mutually-exclusive
options are specified. Except for
.BR \-R ,
.BR \-d ,
and
.BR \-f ,
the
.IR ls
utility is required to accept multiple options from each
mutually-exclusive option set without treating them as errors and to use
the behavior specified by the last option given in each mutually-exclusive
set. Since
.IR ls
is one of the most aliased commands, it is important that the
implementation perform intuitively. For example, if the alias were:
.sp
.RS 4
.nf

alias ls="ls -C"
.fi
.P
.RE
.P
and the user typed
.IR ls
.BR \-1
(one), single-text-column output should result, not an error.
.P
The
.BR \-g ,
.BR \-l
(ell),
.BR \-n ,
and
.BR \-o
options are not mutually-exclusive options. They all enable long format
output. They work together to determine whether the file's owner is
written (no if
.BR \-g
is present), file's group is written (no if
.BR \-o
is present), and if the file's group or owner is written whether it is
written as the name (default) or a string representation of the UID or
GID number (if
.BR \-n
is present). The
.BR \-C ,
.BR \-m ,
.BR \-x ,
and
.BR \-1
(one) are mutually-exclusive options and the first three of these disable
long format output. The
.BR \-1
(one) option does not directly change whether or not long format output
is enabled, but by overriding
.BR \-C ,
.BR \-m ,
and
.BR \-x ,
it can re-enable long format output that had been disabled by one of
these options.
.P
Earlier versions of this standard did not describe the BSD
.BR \-A
option (like
.BR \-a ,
but dot and dot-dot are not written out). It has been added due to
widespread implementation.
.P
Implementations may make
.BR \-q
the default for terminals to prevent trojan horse attacks on terminals
with special escape sequences.
This is not required because:
.IP " *" 4
Some control characters may be useful on some terminals; for example, a
system might write them as
.BR \(dq\e001\(dq 
or
.BR \(dq\(haA\(dq .
.IP " *" 4
Special behavior for terminals is not relevant to applications
portability.
.P
An early proposal specified that the
<\fIoptional\ alternate\ access\ method\ flag\fR> had to be
.BR '\(pl' 
if there was an alternate access method used on the file or
<space>
if there was not. This was changed to be
<space>
if there is not and a single printable character if there is. This was
done for three reasons:
.IP " 1." 4
There are historical implementations using characters other than
.BR '\(pl' .
.IP " 2." 4
There are implementations that vary this character used in that
position to distinguish between various alternate access methods in
use.
.IP " 3." 4
The standard developers did not want to preclude future specifications
that might need a way to specify more than one alternate access
method.
.P
Nonetheless, implementations providing a single alternate access method
are encouraged to use
.BR '\(pl' .
.P
Earlier versions of this standard did not have the
.BR \-k
option, which meant that the
.BR \-s
option could not be used portably as its block size was
implementation-defined, and the units used to specify the
number of blocks occupied by files in a directory in an
.IR ls
.BR \-l
listing were fixed as 512-byte units. The
.BR \-k
option has been added to provide a way for the
.BR \-s
option to be used portably, and for consistency it also changes the
aforementioned units from 512-byte to 1\|024-byte.
.P
The <\fIdate\ and\ time\fP> field in the
.BR \-l
format is specified only for the POSIX locale. As noted, the format can
be different in other locales. No mechanism for defining this is
present in this volume of POSIX.1\(hy2017, as the appropriate vehicle is a messaging system;
that is, the format should be specified as a ``message''.
.SH "FUTURE DIRECTIONS"
Allowing
.BR \-f
to ignore the
.BR \-A ,
.BR \-g ,
.BR \-l ,
.BR \-n ,
.BR \-o ,
and
.BR \-s
options may be removed in a future version.
.P
A future version of this standard may require that if the collating
sequence for the current locale does not have a total ordering of all
characters, any filenames or pathnames that collate equally are
further compared byte-by-byte using the collating sequence for the
POSIX locale.
.SH "SEE ALSO"
.IR "\fIchmod\fR\^",
.IR "\fIfind\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 7.3.2" ", " "LC_COLLATE",
.IR "Section 4.5" ", " "File Access Permissions",
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 12.2" ", " "Utility Syntax Guidelines",
.IR "\fB<sys_stat.h>\fP"
.P
The System Interfaces volume of POSIX.1\(hy2017,
.IR "\fIfstatat\fR\^(\|)"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .