diff options
Diffstat (limited to 'bin/ls/ls.1')
| -rw-r--r-- | bin/ls/ls.1 | 933 |
1 files changed, 933 insertions, 0 deletions
diff --git a/bin/ls/ls.1 b/bin/ls/ls.1 new file mode 100644 index 000000000000..8510ca609cda --- /dev/null +++ b/bin/ls/ls.1 @@ -0,0 +1,933 @@ +.\"- +.\" Copyright (c) 1980, 1990, 1991, 1993, 1994 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the Institute of Electrical and Electronics Engineers, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)ls.1 8.7 (Berkeley) 7/29/94 +.\" $FreeBSD$ +.\" +.Dd August 31, 2020 +.Dt LS 1 +.Os +.Sh NAME +.Nm ls +.Nd list directory contents +.Sh SYNOPSIS +.Nm +.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwxy1\&, +.Op Fl -color Ns = Ns Ar when +.Op Fl D Ar format +.Op Ar +.Sh DESCRIPTION +For each operand that names a +.Ar file +of a type other than +directory, +.Nm +displays its name as well as any requested, +associated information. +For each operand that names a +.Ar file +of type directory, +.Nm +displays the names of files contained +within that directory, as well as any requested, associated +information. +.Pp +If no operands are given, the contents of the current +directory are displayed. +If more than one operand is given, +non-directory operands are displayed first; directory +and non-directory operands are sorted separately and in +lexicographical order. +.Pp +The following options are available: +.Bl -tag -width indent +.It Fl A +Include directory entries whose names begin with a +dot +.Pq Sq Pa \&. +except for +.Pa \&. +and +.Pa .. . +Automatically set for the super-user unless +.Fl I +is specified. +.It Fl B +Force printing of non-printable characters (as defined by +.Xr ctype 3 +and current locale settings) in file names as +.Li \e Ns Va xxx , +where +.Va xxx +is the numeric value of the character in octal. +This option is not defined in +.St -p1003.1-2008 . +.It Fl C +Force multi-column output; this is the default when output is to a terminal. +.It Fl D Ar format +When printing in the long +.Pq Fl l +format, use +.Ar format +to format the date and time output. +The argument +.Ar format +is a string used by +.Xr strftime 3 . +Depending on the choice of format string, this may result in a +different number of columns in the output. +This option overrides the +.Fl T +option. +This option is not defined in +.St -p1003.1-2008 . +.It Fl F +Display a slash +.Pq Ql / +immediately after each pathname that is a directory, +an asterisk +.Pq Ql * +after each that is executable, +an at sign +.Pq Ql @ +after each symbolic link, +an equals sign +.Pq Ql = +after each socket, +a percent sign +.Pq Ql % +after each whiteout, +and a vertical bar +.Pq Ql \&| +after each that is a +.Tn FIFO . +.It Fl G +Enable colorized output. +This option is equivalent to defining +.Ev CLICOLOR +or +.Ev COLORTERM +in the environment and setting +.Fl -color Ns = Ns Ar auto . +(See below.) +This functionality can be compiled out by removing the definition of +.Ev COLORLS . +This option is not defined in +.St -p1003.1-2008 . +.It Fl H +Symbolic links on the command line are followed. +This option is assumed if +none of the +.Fl F , d , +or +.Fl l +options are specified. +.It Fl I +Prevent +.Fl A +from being automatically set for the super-user. +This option is not defined in +.St -p1003.1-2008 . +.It Fl L +If argument is a symbolic link, list the file or directory the link references +rather than the link itself. +This option cancels the +.Fl P +option. +.It Fl P +If argument is a symbolic link, list the link itself rather than the +object the link references. +This option cancels the +.Fl H +and +.Fl L +options. +.It Fl R +Recursively list subdirectories encountered. +.It Fl S +Sort by size (largest file first) before sorting the operands in +lexicographical order. +.It Fl T +When printing in the long +.Pq Fl l +format, display complete time information for the file, including +month, day, hour, minute, second, and year. +The +.Fl D +option gives even more control over the output format. +This option is not defined in +.St -p1003.1-2008 . +.It Fl U +Use time when file was created for sorting or printing. +This option is not defined in +.St -p1003.1-2008 . +.It Fl W +Display whiteouts when scanning directories. +This option is not defined in +.St -p1003.1-2008 . +.It Fl Z +Display each file's MAC label; see +.Xr maclabel 7 . +This option is not defined in +.St -p1003.1-2008 . +.It Fl a +Include directory entries whose names begin with a +dot +.Pq Sq Pa \&. . +.It Fl b +As +.Fl B , +but use +.Tn C +escape codes whenever possible. +This option is not defined in +.St -p1003.1-2008 . +.It Fl c +Use time when file status was last changed for sorting or printing. +.It Fl -color Ns = Ns Ar when +Output colored escape sequences based on +.Ar when , +which may be set to either +.Cm always , +.Cm auto , +or +.Cm never . +.Pp +.Cm always +will make +.Nm +always output color. +If +.Ev TERM +is unset or set to an invalid terminal, then +.Nm +will fall back to explicit +.Tn ANSI +escape sequences without the help of +.Xr termcap 5 . +.Cm always +is the default if +.Fl -color +is specified without an argument. +.Pp +.Cm auto +will make +.Nm +output escape sequences based on +.Xr termcap 5 , +but only if +.Dv stdout +is a tty and either the +.Fl G +flag is specified or the +.Ev COLORTERM +environment variable is set and not empty. +.Pp +.Cm never +will disable color regardless of environment variables. +.Cm never +is the default when neither +.Fl -color +nor +.Fl G +is specified. +.Pp +For compatibility with GNU coreutils, +.Nm +supports +.Cm yes +or +.Cm force +as equivalent to +.Cm always , +.Cm no +or +.Cm none +as equivalent to +.Cm never , +and +.Cm tty +or +.Cm if-tty +as equivalent to +.Cm auto . +.It Fl d +Directories are listed as plain files (not searched recursively). +.It Fl f +Output is not sorted. +This option turns on +.Fl a . +It also negates the effect of the +.Fl r , +.Fl S +and +.Fl t +options. +As allowed by +.St -p1003.1-2008 , +this option has no effect on the +.Fl d , +.Fl l , +.Fl R +and +.Fl s +options. +.It Fl g +This option has no effect. +It is only available for compatibility with +.Bx 4.3 , +where it was used to display the group name in the long +.Pq Fl l +format output. +This option is incompatible with +.St -p1003.1-2008 . +.It Fl h +When used with the +.Fl l +option, use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte +and Petabyte in order to reduce the number of digits to four or fewer +using base 2 for sizes. +This option is not defined in +.St -p1003.1-2008 . +.It Fl i +For each file, print the file's file serial number (inode number). +.It Fl k +This has the same effect as setting environment variable +.Ev BLOCKSIZE +to 1024, except that it also nullifies any +.Fl h +options to its left. +.It Fl l +(The lowercase letter +.Dq ell . ) +List files in the long format, as described in the +.Sx The Long Format +subsection below. +.It Fl m +Stream output format; list files across the page, separated by commas. +.It Fl n +Display user and group IDs numerically rather than converting to a user +or group name in a long +.Pq Fl l +output. +.It Fl o +Include the file flags in a long +.Pq Fl l +output. +This option is incompatible with +.St -p1003.1-2008 . +See +.Xr chflags 1 +for a list of file flags and their meanings. +.It Fl p +Write a slash +.Pq Ql / +after each filename if that file is a directory. +.It Fl q +Force printing of non-graphic characters in file names as +the character +.Ql \&? ; +this is the default when output is to a terminal. +.It Fl r +Reverse the order of the sort. +.It Fl s +Display the number of blocks used in the file system by each file. +Block sizes and directory totals are handled as described in +.Sx The Long Format +subsection below, except (if the long format is not also requested) +the directory totals are not output when the output is in a +single column, even if multi-column output is requested. +.It Fl t +Sort by descending time modified (most recently modified first). +If two files have the same modification timestamp, sort their names +in ascending lexicographical order. +The +.Fl r +option reverses both of these sort orders. +.Pp +Note that these sort orders are contradictory: the time sequence is in +descending order, the lexicographical sort is in ascending order. +This behavior is mandated by +.St -p1003.2 . +This feature can cause problems listing files stored with sequential names on +FAT file systems, such as from digital cameras, where it is possible to have +more than one image with the same timestamp. +In such a case, the photos cannot be listed in the sequence in which +they were taken. +To ensure the same sort order for time and for lexicographical sorting, set the +environment variable +.Ev LS_SAMESORT +or use the +.Fl y +option. +This causes +.Nm +to reverse the lexicographical sort order when sorting files with the +same modification timestamp. +.It Fl u +Use time of last access, +instead of time of last modification +of the file for sorting +.Pq Fl t +or printing +.Pq Fl l . +.It Fl w +Force raw printing of non-printable characters. +This is the default +when output is not to a terminal. +This option is not defined in +.St -p1003.1-2001 . +.It Fl x +The same as +.Fl C , +except that the multi-column output is produced with entries sorted +across, rather than down, the columns. +.It Fl y +When the +.Fl t +option is set, sort the alphabetical output in the same order as the time output. +This has the same effect as setting +.Ev LS_SAMESORT . +See the description of the +.Fl t +option for more details. +This option is not defined in +.St -p1003.1-2001 . +.It Fl 1 +(The numeric digit +.Dq one . ) +Force output to be +one entry per line. +This is the default when +output is not to a terminal. +.It Fl , +(Comma) When the +.Fl l +option is set, print file sizes grouped and separated by thousands using the +non-monetary separator returned by +.Xr localeconv 3 , +typically a comma or period. +If no locale is set, or the locale does not have a non-monetary separator, this +option has no effect. +This option is not defined in +.St -p1003.1-2001 . +.El +.Pp +The +.Fl 1 , C , x , +and +.Fl l +options all override each other; the last one specified determines +the format used. +.Pp +The +.Fl c , u , +and +.Fl U +options all override each other; the last one specified determines +the file time used. +.Pp +The +.Fl S +and +.Fl t +options override each other; the last one specified determines +the sort order used. +.Pp +The +.Fl B , b , w , +and +.Fl q +options all override each other; the last one specified determines +the format used for non-printable characters. +.Pp +The +.Fl H , L +and +.Fl P +options all override each other (either partially or fully); they +are applied in the order specified. +.Pp +By default, +.Nm +lists one entry per line to standard +output; the exceptions are to terminals or when the +.Fl C +or +.Fl x +options are specified. +.Pp +File information is displayed with one or more +.Ao blank Ac Ns s +separating the information associated with the +.Fl i , s , +and +.Fl l +options. +.Ss The Long Format +If the +.Fl l +option is given, the following information +is displayed for each file: +file mode, +number of links, owner name, group name, +MAC label, +number of bytes in the file, abbreviated +month, day-of-month file was last modified, +hour file last modified, minute file last +modified, and the pathname. +.Pp +If the modification time of the file is more than 6 months +in the past or future, and the +.Fl D +or +.Fl T +are not specified, +then the year of the last modification +is displayed in place of the hour and minute fields. +.Pp +If the owner or group names are not a known user or group name, +or the +.Fl n +option is given, +the numeric ID's are displayed. +.Pp +If the file is a character special or block special file, +the device number for the file is displayed in the size field. +If the file is a symbolic link the pathname of the +linked-to file is preceded by +.Dq Li -> . +.Pp +The listing of a directory's contents is preceded +by a labeled total number of blocks used in the file system by the files +which are listed as the directory's contents +(which may or may not include +.Pa \&. +and +.Pa .. +and other files which start with a dot, depending on other options). +.Pp +The default block size is 512 bytes. +The block size may be set with option +.Fl k +or environment variable +.Ev BLOCKSIZE . +Numbers of blocks in the output will have been rounded up so the +numbers of bytes is at least as many as used by the corresponding +file system blocks (which might have a different size). +.Pp +The file mode printed under the +.Fl l +option consists of the +entry type and the permissions. +The entry type character describes the type of file, as +follows: +.Pp +.Bl -tag -width 4n -offset indent -compact +.It Sy \- +Regular file. +.It Sy b +Block special file. +.It Sy c +Character special file. +.It Sy d +Directory. +.It Sy l +Symbolic link. +.It Sy p +.Tn FIFO . +.It Sy s +Socket. +.It Sy w +Whiteout. +.El +.Pp +The next three fields +are three characters each: +owner permissions, +group permissions, and +other permissions. +Each field has three character positions: +.Bl -enum -offset indent +.It +If +.Sy r , +the file is readable; if +.Sy \- , +it is not readable. +.It +If +.Sy w , +the file is writable; if +.Sy \- , +it is not writable. +.It +The first of the following that applies: +.Bl -tag -width 4n -offset indent +.It Sy S +If in the owner permissions, the file is not executable and +set-user-ID mode is set. +If in the group permissions, the file is not executable +and set-group-ID mode is set. +.It Sy s +If in the owner permissions, the file is executable +and set-user-ID mode is set. +If in the group permissions, the file is executable +and setgroup-ID mode is set. +.It Sy x +The file is executable or the directory is +searchable. +.It Sy \- +The file is neither readable, writable, executable, +nor set-user-ID nor set-group-ID mode, nor sticky. +(See below.) +.El +.Pp +These next two apply only to the third character in the last group +(other permissions). +.Bl -tag -width 4n -offset indent +.It Sy T +The sticky bit is set +(mode +.Li 1000 ) , +but not execute or search permission. +(See +.Xr chmod 1 +or +.Xr sticky 7 . ) +.It Sy t +The sticky bit is set (mode +.Li 1000 ) , +and is searchable or executable. +(See +.Xr chmod 1 +or +.Xr sticky 7 . ) +.El +.El +.Pp +The next field contains a +plus +.Pq Ql + +character if the file has an ACL, or a +space +.Pq Ql " " +if it does not. +The +.Nm +utility does not show the actual ACL; +use +.Xr getfacl 1 +to do this. +.Sh ENVIRONMENT +The following environment variables affect the execution of +.Nm : +.Bl -tag -width ".Ev CLICOLOR_FORCE" +.It Ev BLOCKSIZE +If this is set, its value, rounded up to 512 or down to a +multiple of 512, will be used as the block size in bytes by the +.Fl l +and +.Fl s +options. +See +.Sx The Long Format +subsection for more information. +.It Ev CLICOLOR +Use +.Tn ANSI +color sequences to distinguish file types. +See +.Ev LSCOLORS +below. +In addition to the file types mentioned in the +.Fl F +option some extra attributes (setuid bit set, etc.) are also displayed. +The colorization is dependent on a terminal type with the proper +.Xr termcap 5 +capabilities. +The default +.Dq Li cons25 +console has the proper capabilities, +but to display the colors in an +.Xr xterm 1 , +for example, +the +.Ev TERM +variable must be set to +.Dq Li xterm-color . +Other terminal types may require similar adjustments. +Colorization +is silently disabled if the output is not directed to a terminal +unless the +.Ev CLICOLOR_FORCE +variable is defined or +.Fl -color +is set to +.Dq always . +.It Ev CLICOLOR_FORCE +Color sequences are normally disabled if the output is not directed to +a terminal. +This can be overridden by setting this variable. +The +.Ev TERM +variable still needs to reference a color capable terminal however +otherwise it is not possible to determine which color sequences to +use. +.It Ev COLORTERM +See description for +.Ev CLICOLOR +above. +.It Ev COLUMNS +If this variable contains a string representing a +decimal integer, it is used as the +column position width for displaying +multiple-text-column output. +The +.Nm +utility calculates how +many pathname text columns to display +based on the width provided. +(See +.Fl C +and +.Fl x . ) +.It Ev LANG +The locale to use when determining the order of day and month in the long +.Fl l +format output. +See +.Xr environ 7 +for more information. +.It Ev LSCOLORS +The value of this variable describes what color to use for which +attribute when colors are enabled with +.Ev CLICOLOR +or +.Ev COLORTERM . +This string is a concatenation of pairs of the format +.Ar f Ns Ar b , +where +.Ar f +is the foreground color and +.Ar b +is the background color. +.Pp +The color designators are as follows: +.Pp +.Bl -tag -width 4n -offset indent -compact +.It Sy a +black +.It Sy b +red +.It Sy c +green +.It Sy d +brown +.It Sy e +blue +.It Sy f +magenta +.It Sy g +cyan +.It Sy h +light grey +.It Sy A +bold black, usually shows up as dark grey +.It Sy B +bold red +.It Sy C +bold green +.It Sy D +bold brown, usually shows up as yellow +.It Sy E +bold blue +.It Sy F +bold magenta +.It Sy G +bold cyan +.It Sy H +bold light grey; looks like bright white +.It Sy x +default foreground or background +.El +.Pp +Note that the above are standard +.Tn ANSI +colors. +The actual display may differ +depending on the color capabilities of the terminal in use. +.Pp +The order of the attributes are as follows: +.Pp +.Bl -enum -offset indent -compact +.It +directory +.It +symbolic link +.It +socket +.It +pipe +.It +executable +.It +block special +.It +character special +.It +executable with setuid bit set +.It +executable with setgid bit set +.It +directory writable to others, with sticky bit +.It +directory writable to others, without sticky bit +.El +.Pp +The default is +.Qq "exfxcxdxbxegedabagacad" , +i.e., blue foreground and +default background for regular directories, black foreground and red +background for setuid executables, etc. +.It Ev LS_COLWIDTHS +If this variable is set, it is considered to be a +colon-delimited list of minimum column widths. +Unreasonable +and insufficient widths are ignored (thus zero signifies +a dynamically sized column). +Not all columns have changeable widths. +The fields are, +in order: inode, block count, number of links, user name, +group name, flags, file size, file name. +.It Ev LS_SAMESORT +If this variable is set, the +.Fl t +option sorts the names of files with the same modification timestamp in the same +sense as the time sort. +See the description of the +.Fl t +option for more details. +.It Ev TERM +The +.Ev CLICOLOR +and +.Ev COLORTERM +functionality depends on a terminal type with color capabilities. +.It Ev TZ +The timezone to use when displaying dates. +See +.Xr environ 7 +for more information. +.El +.Sh EXIT STATUS +.Ex -std +.Sh EXAMPLES +List the contents of the current working directory in long format: +.Pp +.Dl $ ls -l +.Pp +In addition to listing the contents of the current working directory in +long format, show inode numbers, file flags (see +.Xr chflags 1 ) , +and suffix each filename with a symbol representing its file type: +.Pp +.Dl $ ls -lioF +.Pp +List the files in +.Pa /var/log , +sorting the output such that the mostly recently modified entries are +printed first: +.Pp +.Dl $ ls -lt /var/log +.Sh COMPATIBILITY +The group field is now automatically included in the long listing for +files in order to be compatible with the +.St -p1003.2 +specification. +.Sh SEE ALSO +.Xr chflags 1 , +.Xr chmod 1 , +.Xr getfacl 1 , +.Xr sort 1 , +.Xr xterm 1 , +.Xr localeconv 3 , +.Xr strftime 3 , +.Xr strmode 3 , +.Xr termcap 5 , +.Xr maclabel 7 , +.Xr sticky 7 , +.Xr symlink 7 , +.Xr getfmac 8 +.Sh STANDARDS +With the exception of options +.Fl g , n +and +.Fl o , +the +.Nm +utility conforms to +.St -p1003.1-2001 +and +.St -p1003.1-2008 . +The options +.Fl B , D , G , I , T , U , W , Z , b , h , w , y +and +.Fl , +are non-standard extensions. +.Pp +The ACL support is compatible with +.Tn IEEE +Std\~1003.2c +.Pq Dq Tn POSIX Ns .2c +Draft\~17 +(withdrawn). +.Sh HISTORY +An +.Nm +command appeared in +.At v1 . +.Sh BUGS +To maintain backward compatibility, the relationships between the many +options are quite complex. +.Pp +The exception mentioned in the +.Fl s +option description might be a feature that was +based on the fact that single-column output +usually goes to something other than a terminal. +It is debatable whether this is a design bug. +.Pp +.St -p1003.2 +mandates opposite sort orders for files with the same timestamp when +sorting with the +.Fl t +option. |