mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-05 09:14:03 +00:00
720 lines
16 KiB
Groff
720 lines
16 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.
|
|
.\" 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 April 4, 2008
|
|
.Dt LS 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ls
|
|
.Nd list directory contents
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl ABCFGHILPRSTUWZabcdfghiklmnopqrstuwx1
|
|
.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.
|
|
.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.
|
|
.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
|
|
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 , d ,
|
|
or
|
|
.Fl l
|
|
options are specified.
|
|
.It Fl I
|
|
Prevent
|
|
.Fl A
|
|
from being automatically set for the super-user.
|
|
.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.
|
|
.It Fl U
|
|
Use time when file was created for sorting or printing.
|
|
.It Fl W
|
|
Display whiteouts when scanning directories.
|
|
.It Fl Z
|
|
Display each file's MAC label; see
|
|
.Xr maclabel 7 .
|
|
.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.
|
|
.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 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.
|
|
.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.
|
|
.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 time modified (most recently modified
|
|
first) before sorting the operands in 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 w
|
|
Force raw printing of non-printable characters.
|
|
This is the default
|
|
when output is not to a terminal.
|
|
.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 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.
|
|
.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 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 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 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
|
|
.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.
|
|
.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 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
|
|
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 .
|
|
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 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 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 getfacl 1 ,
|
|
.Xr sort 1 ,
|
|
.Xr xterm 1 ,
|
|
.Xr strftime 3 ,
|
|
.Xr strmode 3 ,
|
|
.Xr termcap 5 ,
|
|
.Xr maclabel 7 ,
|
|
.Xr symlink 7 ,
|
|
.Xr getfmac 8 ,
|
|
.Xr sticky 8
|
|
.Sh STANDARDS
|
|
With the exception of options
|
|
.Fl I , g , n
|
|
and
|
|
.Fl o ,
|
|
the
|
|
.Nm
|
|
utility conforms to
|
|
.St -p1003.1-2001 .
|
|
.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.
|