diff options
Diffstat (limited to 'bin/ls/ls.1')
| -rw-r--r-- | bin/ls/ls.1 | 516 |
1 files changed, 516 insertions, 0 deletions
diff --git a/bin/ls/ls.1 b/bin/ls/ls.1 new file mode 100644 index 0000000..1bd9161 --- /dev/null +++ b/bin/ls/ls.1 @@ -0,0 +1,516 @@ +.\" $NetBSD: ls.1,v 1.80 2017/07/03 21:33:23 wiz Exp $ +.\" +.\" 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 +.\" +.Dd August 10, 2016 +.Dt LS 1 +.Os +.Sh NAME +.Nm ls +.Nd list directory contents +.Sh SYNOPSIS +.Nm +.Op Fl 1AaBbCcdFfghikLlMmnOoPpqRrSsTtuWwXx +.Op Ar +.Sh DESCRIPTION +For each +.Ar file +operand that names a file of a type other than +directory, +.Nm +displays its name as well as any requested, +associated information. +For each +.Ar file +operand that names a 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 \&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 A +List all entries except for +.Ql \&. +and +.Ql \&.. . +Always set for the super-user. +.It Fl a +Include directory entries whose names begin with a +dot +.Pq Sq \&. . +.It Fl B +Force printing of non-graphic characters in file names as \exxx, where xxx +is the numeric value of the character in octal. +.It Fl b +As +.Fl B , +but use C escape codes whenever possible. +.It Fl C +Force multi-column output; this is the default when output is to a terminal. +.It Fl c +Use time when file status was last changed, +instead of time of last modification of the file for printing +.Pq Fl l +or sorting +.Pq Fl t . +Overrides +.Fl u . +.It Fl d +Directories are listed as plain files (not searched recursively) and +symbolic links in the argument list are not followed. +Turns off +.Fl R +if also given. +.It Fl F +Display a slash +.Pq Sq \&/ +immediately after each pathname that is a directory, +an asterisk +.Pq Sq \&* +after each that is executable, +an at sign +.Pq Sq \&@ +after each symbolic link, +a percent sign +.Pq Sq \&% +after each whiteout, +an equal sign +.Pq Sq \&= +after each socket, +and a vertical bar +.Pq Sq \&| +after each that is a +.Tn FIFO . +.It Fl f +Output is not sorted. +This option implies +.Fl a . +.It Fl g +The same as +.Fl l , +except that the owner is not printed. +.It Fl h +Modifies the +.Fl l +and +.Fl s +options, causing the sizes to be reported in bytes displayed in a human +readable format. +Overrides +.Fl k +and +.Fl M . +.It Fl i +For each file, print the file's file serial number (inode number). +.It Fl k +Modifies the +.Fl s +option, causing the sizes to be reported in kilobytes. +Overrides +.Fl h . +.It Fl L +For each file, if it's a link, evaluate file information and file type +of the referenced file and not the link itself; however still print +the link name, unless used with +.Fl l , +for example. +.It Fl l +(The lowercase letter +.Dq ell ) . +List in long format. +(See below.) +.It Fl M +Modifies the +.Fl l +and +.Fl s +options, causing the sizes or block counts reported to be separated with +commas (or a locale appropriate separator) resulting in a more readable +output. +Overrides +.Fl h ; +does not override +.Fl k . +.It Fl m +Stream output format; list files across the page, separated by commas. +.It Fl n +The same as +.Fl l , +except that +the owner and group IDs are displayed numerically rather than converting +to a owner or group name. +.It Fl O +Output only leaf files (not directories), eliding other +.Nm +output. +.It Fl o +Include the file flags in a long +.Pq Fl l +output. +If no file flags are set, +.Dq - +is displayed. +(See +.Xr chflags 1 +for a list of possible flags and their meanings.) +.It Fl P +Print the full pathname for each file. +.It Fl p +Display a slash +.Pq Sq \&/ +immediately after each pathname that is a directory. +.It Fl q +Force printing of non-printable characters in file names as +the character +.Sq \&? ; +this is the default when output is to a terminal. +.It Fl R +Recursively list subdirectories encountered. +See also +.Fl d . +.It Fl r +Reverse the order of the sort to get reverse +lexicographical order or the smallest or oldest entries first. +.It Fl S +Sort by size, largest file first. +.It Fl s +Display the number of file system blocks actually used by each file, in units +of 512 bytes or +.Ev BLOCKSIZE +(see +.Sx ENVIRONMENT ) +where partial units are rounded up to the +next integer value. +If the output is to a terminal, a total sum for all the file +sizes is output on a line before the listing. +.It Fl T +When used with the +.Fl l +(the lowercase letter +.Dq ell ) +option, display complete time information for the file, including +month, day, hour, minute, second, and year. +.It Fl t +Sort by time modified (most recently modified +first) before sorting the operands by lexicographical +order. +.It Fl u +Use time of last access, +instead of last modification +of the file for printing +.Pq Fl l +or sorting +.Pq Fl t . +Overrides +.Fl c . +.It Fl W +Display whiteouts when scanning directories. +.It Fl w +Force raw printing of non-printable characters. +This is the default when output is not to a terminal. +.It Fl x +Multi-column output sorted across the page rather than down the page. +.It Fl X +Don't cross mount points when recursing. +.El +.Pp +The +.Fl B , +.Fl b , +.Fl q , +and +.Fl w +options all override each other; the last one specified determines +the format used for non-printable characters. +.Pp +The +.Fl 1 , +.Fl C , +.Fl g , +.Fl l , +.Fl m , +and +.Fl x +options all override each other; the last one specified determines +the format used with the exception that if both +.Fl l +and +.Fl g +are specified, +.Fl l +will always override +.Fl g , +even if +.Fl g +was specified last. +.Pp +By default, +.Nm +lists one entry per line to standard +output; the exceptions are to terminals or when the +.Fl C +or +.Fl m +options are specified. +.Pp +File information is displayed with one or more +.Aq blank +characters separating the information associated with the +.Fl i , +.Fl l , +and +.Fl s +options. +.Ss The Long Format +If the +.Fl l +option is given, the following information +is displayed for each file: +.Bl -item -offset indent -compact +.It +file mode +.It +number of links +.It +owner name +.It +group name +.It +file flags (if +.Fl o +given) +.It +number of bytes in the file +.It +abbreviated month file was last modified +.It +day-of-month file was last modified +.It +hour and minute file was last modified +.It +pathname +.El +.Pp +In addition, for each directory whose contents are displayed, the total +number of file system blocks in units of 512 bytes or +.Ev BLOCKSIZE +(see +.Sx ENVIRONMENT ) +used by the files in the directory is displayed on a line by itself +immediately before the information for the files in the directory. +.Pp +If the owner or group names are not a known owner 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 major and minor device numbers for the file are displayed +in the size field. +If the file is a symbolic link the pathname of the +linked-to file is preceded by +.Dq \-> . +.Pp +The file mode printed under the +.Fl l +option consists of the entry type, owner permissions, group +permissions, and other 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 a +Archive state 1. +.It Sy A +Archive state 2. +.It Sy b +Block special file. +.It Sy c +Character special file. +.It Sy d +Directory. +.It Sy l +Symbolic link. +.It Sy p +FIFO. +.It Sy s +Socket link. +.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 number of bytes displayed for a directory is a function of the +number of +.Xr dirent 3 +structures in the directory, not all of which may be allocated to +any existing file. +.Sh ENVIRONMENT +The following environment variables affect the execution of +.Nm : +.Bl -tag -width BLOCKSIZE +.It Ev BLOCKSIZE +If the environment variable +.Ev BLOCKSIZE +is set, and the +.Fl k +option is not specified, the block counts +(see +.Fl l +and +.Fl s ) +will be displayed in units of that size block. +.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 . ) +.It Ev TZ +The timezone to use when displaying dates. +See +.Xr environ 7 +for more information. +.El +.Sh EXIT STATUS +.Ex -std +.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 stat 2 , +.Xr dirent 3 , +.Xr getbsize 3 , +.Xr sticky 7 , +.Xr symlink 7 +.Sh STANDARDS +The +.Nm +utility is expected to be a superset of the +.St -p1003.2 +specification. +.Sh HISTORY +An +.Nm +utility appeared in +.At v1 . |