diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/mageia-cauldron/man1p/ls.1p | 1152 |
1 files changed, 1152 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1p/ls.1p b/upstream/mageia-cauldron/man1p/ls.1p new file mode 100644 index 00000000..88c39cca --- /dev/null +++ b/upstream/mageia-cauldron/man1p/ls.1p @@ -0,0 +1,1152 @@ +'\" 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 . |