ls.1p (31842B)
- '\" 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 .