560 lines
14 KiB
Groff
560 lines
14 KiB
Groff
.\" 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. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgment:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. 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 July 29, 1994
|
|
.Dt LS 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ls
|
|
.Nd list directory contents
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl ABCFGHLPRTWabcdfgiklnoqrstu1
|
|
.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
|
|
List all entries except for
|
|
.Ql .\&
|
|
and
|
|
.Ql .. .
|
|
Always set for the super-user.
|
|
.It Fl B
|
|
Force printing of non-graphic characters in file names as \\xxx,
|
|
where xxx is the numeric value of the character in octal.
|
|
.It Fl C
|
|
Force multi-column output; this is the default when output is to a terminal.
|
|
.It Fl F
|
|
Display a slash (/) immediately after each pathname
|
|
that is a directory, an asterisk (*) after each that is
|
|
executable,
|
|
an at sign (@) after each symbolic link,
|
|
an equals sign (=) after each socket,
|
|
a percent sign (%) after each whiteout,
|
|
and a vertical bar (|) after each that is a
|
|
.Tn FIFO .
|
|
.It Fl G
|
|
Enable colorized output. This option is equivalent to defining
|
|
.Ev CLICOLOR
|
|
in the environment. (See below).
|
|
.It Fl H
|
|
Symbolic links on the command line are followed. This option is assumed if
|
|
none of the
|
|
.Fl F ,
|
|
.Fl d ,
|
|
or
|
|
.Fl l
|
|
options are specified.
|
|
.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 T
|
|
Display complete time information for the file, including
|
|
month, day, hour, minute, second, and year.
|
|
.It Fl W
|
|
Display whiteouts when scanning directories.
|
|
.It Fl a
|
|
Include directory entries whose names begin with a
|
|
dot (.).
|
|
.It Fl b
|
|
As
|
|
.Fl B ,
|
|
but use C escape codes whenever possible.
|
|
.It Fl c
|
|
Use time when file status was last changed for sorting or printing.
|
|
.It Fl d
|
|
Directories are listed as plain files (not searched recursively).
|
|
.It Fl f
|
|
Output is not sorted.
|
|
.It Fl g
|
|
This option is deprecated and is only available for compatibility
|
|
with
|
|
.Bx 4.3 ;
|
|
it was used to display the group name in the long
|
|
.Pq Fl l
|
|
format output.
|
|
.It Fl i
|
|
For each file, print the file's file serial number (inode number).
|
|
.It Fl k
|
|
If the
|
|
.Fl s
|
|
option is specified, print the file size allocation in kilobytes,
|
|
not blocks. This option overrides the environment variable BLOCKSIZE.
|
|
.It Fl l
|
|
(The lowercase letter ``ell.'') List in long format.
|
|
(See below.)
|
|
If the output is to a terminal, a total sum for all the file
|
|
sizes is output on a line before the long listing.
|
|
.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.
|
|
.It Fl q
|
|
Force printing of non-graphic characters in file names as
|
|
the character `?'; this is the default when output is to a terminal.
|
|
.It Fl r
|
|
Reverse the order of the sort to get reverse
|
|
lexicographical order or the oldest entries first.
|
|
.It Fl s
|
|
Display the number of file system blocks actually used by each file, in units
|
|
of 512 bytes, 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. The environment variable
|
|
BLOCKSIZE overrides the unit size of 512 bytes.
|
|
.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 sorting
|
|
.Pq Fl t
|
|
or printing
|
|
.Pq Fl l .
|
|
.It Fl \&1
|
|
(The numeric digit ``one.'') Force output to be
|
|
one entry per line.
|
|
This is the default when
|
|
output is not to a terminal.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fl 1 ,
|
|
.Fl C ,
|
|
and
|
|
.Fl l
|
|
options all override each other; the last one specified determines
|
|
the format used.
|
|
.Pp
|
|
The
|
|
.Fl c
|
|
and
|
|
.Fl u
|
|
options override each other; the last one specified determines
|
|
the file time used.
|
|
.Pp
|
|
The
|
|
.Fl B ,
|
|
.Fl b
|
|
and
|
|
.Fl q
|
|
options all override each other; the last one specified determines
|
|
the format used for non-printable characters.
|
|
.Pp
|
|
The
|
|
.Fl H ,
|
|
.Fl 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
|
|
option is specified.
|
|
.Pp
|
|
File information is displayed with one or more
|
|
<blank>s separating the information associated with the
|
|
.Fl i ,
|
|
.Fl 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,
|
|
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.
|
|
In addition, for each directory whose contents are displayed, the total
|
|
number of 512-byte blocks 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 modification time of the file is more than 6 months
|
|
in the past or future, 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 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, and group permissions.
|
|
The entry type character describes the type of file, as
|
|
follows:
|
|
.Pp
|
|
.Bl -tag -width 4n -offset indent -compact
|
|
.It Sy b
|
|
Block special file.
|
|
.It Sy c
|
|
Character special file.
|
|
.It Sy d
|
|
Directory.
|
|
.It Sy l
|
|
Symbolic link.
|
|
.It Sy s
|
|
Socket link.
|
|
.It Sy p
|
|
.Tn FIFO .
|
|
.It Sy \-
|
|
Regular file.
|
|
.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 8 . )
|
|
.It Sy t
|
|
The sticky bit is set (mode
|
|
.Li 1000 ) ,
|
|
and is searchable or executable.
|
|
(See
|
|
.Xr chmod 1
|
|
or
|
|
.Xr sticky 8 . )
|
|
.El
|
|
.El
|
|
.Sh EXAMPLES
|
|
The following is how to do an
|
|
.Nm
|
|
listing sorted by size (and shows why
|
|
.Nm
|
|
does not need a separate option for this):
|
|
.Pp
|
|
.Dl "ls -l | sort -n +4"
|
|
.Pp
|
|
Additionally, the
|
|
.Fl r
|
|
flag to
|
|
.Xr sort 1
|
|
may be used
|
|
to get the results sorted from largest to smallest (a reverse sort).
|
|
.Sh DIAGNOSTICS
|
|
.Ex -std
|
|
.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, the block counts
|
|
(see
|
|
.Fl s )
|
|
will be displayed in units of that size block.
|
|
.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 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 xterm-color .
|
|
Other terminal types may require similar adjustments. Colorization
|
|
is silently disabled if the output isn't directed to a terminal
|
|
unless the
|
|
.Ev CLICOLOR_FORCE
|
|
variable is defined.
|
|
.It Ev CLICOLOR_FORCE
|
|
Color sequences are normally disabled if the output isn't directed to
|
|
a terminal. This can be overridden by setting this flag.
|
|
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 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 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 .
|
|
This string is a concatenation of pairs of the format
|
|
.Sy fb ,
|
|
where
|
|
.Sy f
|
|
is the foreground color and
|
|
.Sy b
|
|
is the background color.
|
|
.Pp
|
|
The color designators are as follows:
|
|
.Pp
|
|
.Bl -tag -width 4n -offset indent -compact
|
|
.It Sy 0
|
|
black
|
|
.It Sy 1
|
|
red
|
|
.It Sy 2
|
|
green
|
|
.It Sy 3
|
|
brown
|
|
.It Sy 4
|
|
blue
|
|
.It Sy 5
|
|
magenta
|
|
.It Sy 6
|
|
cyan
|
|
.It Sy 7
|
|
light grey
|
|
.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 "4x5x2x3x1x464301060203", 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 TERM
|
|
The
|
|
.Ev CLICOLOR
|
|
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 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 sort 1 ,
|
|
.Xr xterm 1 ,
|
|
.Xr termcap 5 ,
|
|
.Xr symlink 7 ,
|
|
.Xr sticky 8
|
|
.Sh HISTORY
|
|
An
|
|
.Nm
|
|
command appeared in
|
|
.At v1 .
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
function is expected to be a superset of the
|
|
.St -p1003.2
|
|
specification.
|
|
.Sh BUGS
|
|
To maintain backward compatibility, the relationships between the many
|
|
options are quite complex.
|