LS(1) LS(1)
NAME
ls, dir, vdir - list directory contents
SYNOPSIS
ls [options] [file...]
dir [file...]
vdir [file...]
POSIX options: [-CFRacdilqrtu1] [--]
GNU options (shortest form): [-1abcdfghiklmnopqrstuvwx-
ABCDFGHLNQRSUX] [-w cols] [-T cols] [-I pattern]
[--full-time] [--show-control-chars] [--block-size=size]
[--format={long,verbose,commas,across,vertical,single-col-
umn}] [--sort={none,time,size,extension}]
[--time={atime,access,use,ctime,status}]
[--color[={none,auto,always}]] [--help] [--version] [--]
DESCRIPTION
The program ls lists first its non-directory file argu-
ments, and then for each directory argument all listable
files contained within that directory. If no non-option
arguments are present, a default argument `.' (the current
directory) is assumed. The -d option causes directories
to be treated as non-directory arguments. A file is
listable when either its name does not start with `.', or
the -a option is given.
Each of the lists of files (that of non-directory files,
and for each directory the list of files inside) is sorted
separately according to the collating sequence in the cur-
rent locale. When the -l option is given, each list is
preceded by a summary line giving the total size of all
files in the list, measured in semi-kilobytes (512 B).
The output is to stdout, one entry per line, unless multi-
column output is requested by the -C option. However, for
output to a terminal, it is undefined whether the output
will be single-column or multi-column. The options -1 and
-C can be used to force single-column and multi-column
output, respectively.
POSIX OPTIONS
-C List files in columns, sorted vertically.
-F Suffix each directory name with `/', each FIFO name
with `|', and each name of an executable with `*'.
-R Recursively list subdirectories encountered.
-a Include files with a name starting with `.' in the
listing.
-c Use the status change time instead of the
GNU fileutils 4.0 November 1998 1
LS(1) LS(1)
modification time for sorting (with -t) or listing
(with -l).
-d List names of directories like other files, rather
than listing their contents.
-i Precede the output for the file by the file serial
number (i-node number).
-l Write (in single-column format) the file mode, the
number of links to the file, the owner name, the
group name, the size of the file (in bytes), the
timestamp, and the filename.
The file types are as follows: - for an ordinary
file, d for a directory, b for a block special
device, c for a character special device, l for a
symbolic link, p for a fifo, s for a socket.
By default, the timestamp shown is that of the last
modification; the options -c and -u select the
other two timestamps. For device special files the
size field is commonly replaced by the major and
minor device numbers.
-q Output nonprintable characters in a filename as
question marks. (This is permitted to be the
default for output to a terminal.)
-r Reverse the order of the sort.
-t Sort by the timestamp shown.
-u Use the time of last access instead of the modifi-
cation time for sorting (with -t) or listing (with
-l).
-1 For single-column output.
-- Terminate option list.
GNU DETAILS
If standard output is a terminal, the output is in columns
(sorted vertically).
dir (also installed as d) is equivalent to `ls -C -b';
that is, files are by default listed in columns, sorted
vertically. vdir (also installed as v) is equivalent to
`ls -l -b'; that is, files are by default listed in long
format.
GNU OPTIONS
-1, --format=single-column
List one file per line. This is the default for
GNU fileutils 4.0 November 1998 2
LS(1) LS(1)
when standard output is not a terminal.
-a, --all
List all files in directories, including all files
that start with `.'.
-b, --escape, --quoting-style=escape
Quote nongraphic characters in file names using
alphabetic and octal backslash sequences like those
used in C. This option is the same as -Q except
that filenames are not surrounded by double-quotes.
-c, --time=ctime, --time=status
Sort directory contents according to the files'
status change time (the `ctime' in the inode). If
the long listing format is being used (-l) print
the status change time instead of the modification
time.
-d, --directory
List names of directories like other files, rather
than listing their contents.
-f Do not sort directory contents; list them in what-
ever order they are stored on the disk. Also
enables -a and -U and disables -l, --color, -s, and
-t if they were specified before the -f.
-g Ignored; for Unix compatibility.
-h, --human-readable
Append a size letter, such as M for binary
megabytes (`mebibytes'), to each size. (New in
fileutils-4.0.)
-i, --inode
Print the inode number (also called the file serial
number and index number) of each file to the left
of the file name. (This number uniquely identifies
each file within a particular filesystem)
-k, --kilobytes
If file sizes are being listed, print them in kilo-
bytes.
-l, --format=long, --format=verbose
In addition to the name of each file, print the
file type, permissions, number of hard links, owner
name, group name, size in bytes, and timestamp (the
modification time unless other times are selected).
For files with a time that is more than 6 months
old or more than 1 hour into the future, the times-
tamp contains the year instead of the time of day.
GNU fileutils 4.0 November 1998 3
LS(1) LS(1)
For each directory that is listed, preface the
files with a line `total blocks', where blocks is
the total disk space used by all files in that
directory. By default, 1024-byte blocks are used;
if the environment variable POSIXLY_CORRECT is set,
512-byte blocks are used (unless the -k option is
given). The blocks computed counts each hard link
separately; this is arguably a deficiency.
The permissions listed are similar to symbolic mode
specifications but ls combines multiple bits into
the third character of each set of permissions
s If the setuid or setgid bit and the corre-
sponding executable bit are both set.
S If the setuid or setgid bit is set but the
corresponding executable bit is not set.
t If the sticky bit and the other-executable
bit are both set.
T If the sticky bit is set but the other-exe-
cutable bit is not set.
x If the executable bit is set and none of the
above apply.
- Otherwise.
-m, --format=commas
List files horizontally, with as many as will fit
on each line, each separated by a comma and a
space.
-n, --numeric-uid-gid
List the numeric UID and GID instead of the names.
-o Produce long format directory listings, but don't
display group information. It is equivalent to
using --format=long --no-group. This option is
provided for compatibility with other versions of
ls.
-p, --file-type, --indicator-style=file-type
Append a character to each file name indicating the
file type. This is like -F except that executables
aren't marked. (In fact fileutils-4.0 treats the
--file-type option like --classify.)
-q, --hide-control-chars
Print question marks instead of nongraphic charac-
ters in file names. This is the default.
GNU fileutils 4.0 November 1998 4
LS(1) LS(1)
-r, --reverse
Sort directory contents in reverse order.
-s, --size
Print the size of each file in 1024-byte blocks to
the left of the file name. If the environment
variable POSIXLY_CORRECT is set, 512-byte blocks
are used instead, unless the -k option is given.
-t, --sort=time
Sort by modification time (the `mtime' in the
inode) instead of alphabetically, with the newest
files listed first.
-u, --time=atime, --time=access, --time=use
Sort directory contents according to the files'
last access time instead of the modification time
(the `atime' in the inode). If the long listing
format is being used, print the last access time
instead of the modification time.
-v Sort directory contents according to the files'
version. This takes into account the fact that
filenames frequently include indices or version
numbers. Standard sorting functions usually do not
produce the ordering that people expect because
comparisons are made on a character-by-character
basis. The version sort adresses this problem, and
is especially useful when browsing directories that
contain many files with indices/version numbers in
their names. For example:
> ls -1 > ls -1v
foo.zml-1.gz foo.zml-1.gz
foo.zml-100.gz foo.zml-12.gz
foo.zml-12.gz foo.zml-25.gz
foo.zml-25.gz foo.zml-100.gz
Note also that numeric parts with leading zeroes
are considered as fractional:
> ls -1 > ls -1v
abc-1.007.tgz abc-1.007.tgz
abc-1.012b.tgz abc-1.01a.tgz
abc-1.01a.tgz abc-1.012b.tgz
(New in fileutils-4.0.)
-w, --width cols
Assume the screen is cols columns wide. The
default is taken from the terminal driver if possi-
ble; otherwise the environment variable COLUMNS is
used if it is set; otherwise the default is 80.
GNU fileutils 4.0 November 1998 5
LS(1) LS(1)
-x, --format=across, --format=horizontal
List the files in columns, sorted horizontally.
-A, --almost-all
List all files in directories, except for `.' and
`..'.
-B, --ignore-backups
Do not list files that end with `~', unless they
are given on the command line.
-C, --format=vertical
List files in columns, sorted vertically. This is
the default if standard output is a terminal. It is
always the default for dir and d.
-D, --dired
With the long listing (-l) format, print an addi-
tional line after the main output:
//DIRED// BEG1 END1 BEG2 END2 ...
The BEGn and ENDn are unsigned integers which
record the byte position of the beginning and end
of each file name in the output. This makes it easy
for Emacs to find the names, even when they contain
unusual characters such as space or newline, with-
out fancy searching.
If directories are being listed recursively (-R),
output a similar line after each subdirectory:
//SUBDIRED// BEG1 END1 ...
-F, --classify, --indicator-style=classify
Append a character to each file name indicating the
file type. For regular files that are executable,
append a `*'. The file type indicators are `/' for
directories, `@' for symbolic links, `|' for FIFOs,
`=' for sockets, and nothing for regular files.
-G, --no-group
Inhibit display of group information in a long for-
mat directory listing.
-H, --si
Do the same as for -h, but use the official SI
units (with powers of 1000 instead of 1024, so that
M stands for 1000000 instead of 1048576). (New in
fileutils-4.0.)
-I, --ignore=pattern
Do not list files whose names match the shell pat-
tern pattern (not regular expression) unless they
are given on the command line. As in the shell, an
initial `.' in a filename does not match a wildcard
GNU fileutils 4.0 November 1998 6
LS(1) LS(1)
at the start of pattern.
-L, --dereference
List the file information corresponding to the
referrents of symbolic links rather for the links
themselves.
-N, --literal
Do not quote file names.
-Q, --quote-name, --quoting-style=c
Enclose file names in double quotes and quote non-
graphic characters as in C.
-R, --recursive
List the contents of all directories recursively.
-S, --sort=size
Sort directory contents by file size instead of
alphabetically, with the largest files listed
first.
-T, --tabsize cols
Assume that each tabstop is cols columns wide. The
default is 8 and can be overridden by the environ-
ment variable TABSIZE when POSIXLY_CORRECT is not
set. ls uses tabs where possible in the output,
for efficiency. If cols is zero, do not use tabs at
all.
-U, --sort=none
Do not sort directory contents; list them in what-
ever order they are stored on the disk. (The dif-
ference between -U and -f is that the former
doesn't disable or enable options.) This is espe-
cially useful when listing very large directories,
since not doing any sorting can be noticeably
faster.
-X, --sort=extension
Sort directory contents alphabetically by file
extension (characters after the last `.'); files
with no extension are sorted first.
--block-size=size
Print sizes in blocks of size bytes. (New in file-
utils-4.0.)
--color[=when]
Specify whether to use color for distinguishing
file types. Colors are specified using the LS_COL-
ORS environment variable. For information on how
to set this variable, see dircolors(1). when may
be omitted, or one of:
GNU fileutils 4.0 November 1998 7
LS(1) LS(1)
none Do not use color at all. This is the
default.
auto Only use color if standard output is a ter-
minal.
always Always use color. Specifying --color and no
when is equivalent to --color=always.
--full-time
List times in full, rather than using the standard
abbreviation heuristics. The format is the same as
date(1)'s default; it's not possible to change
this, but you can extract out the date string with
cut(1) and then pass the result to `date -d'.
This is most useful because the time output
includes the seconds. (Unix filesystems store file
timestamps only to the nearest second, so this
option shows all the information there is.) For
example, this can help when you have a Makefile
that is not regenerating files properly.
--quoting-style=word
Use style word to quote output names. The word
should be one of the following:
literal
Output names as-is. This is the default
behavior of ls.
shell Quote names for the shell if they contain
shell metacharacters or would cause ambigu-
ous output.
shell-always
Quote names for the shell, even if they
would normally not require quoting.
c Quote names as for a C language string; this
is the same as the -Q option.
escape Quote as with c except omit the surrounding
double-quote characters; this is the same as
the -b option.
A default value for this option can be specified
with the environment variable QUOTING_STYLE. (See
ENVIRONMENT below.)
--show-control-chars
Print nongraphic characters as-is in file names.
This is the default unless the output is a terminal
and the program is ls.
GNU fileutils 4.0 November 1998 8
LS(1) LS(1)
GNU STANDARD OPTIONS
--help Print a usage message on standard output and exit
successfully.
--version
Print version information on standard output, then
exit successfully.
-- Terminate option list.
ENVIRONMENT
The variable POSIXLY_CORRECT determines the choice of
unit. If it is not set, then the variable TABSIZE deter-
mines the number of chars per tab stop. The variable
COLUMNS (when it contains the representation of a decimal
integer) determines the output column width (for use with
the -C option). Filenames must not be truncated to make
them fit a multi-column output.
The variables LANG, LC_ALL, LC_COLLATE, LC_CTYPE, LC_MES-
SAGES and LC_TIME have the usual meaning. The variable TZ
gives the time zone for time strings written by ls. The
variable LS_COLORS is used to specify the colors used.
The variable QUOTING_STYLE is used to specify the default
value for the --quoting-style option. It currently
defaults to literal, though the authors have warned that
this default may change to shell in some future version of
ls.
BUGS
On BSD systems, the -s option reports sizes that are half
the correct values for files that are NFS-mounted from HP-
UX systems. On HP-UX systems, ls reports sizes that are
twice the correct values for files that are NFS-mounted
from BSD systems. This is due to a flaw in HP-UX; it also
affects the HP-UX ls program.
CONFORMING TO
POSIX 1003.2
SEE ALSO
dircolors(1)
NOTES
This page describes ls as found in the fileutils-4.0 pack-
age; other versions may differ slightly. Mail corrections
and additions to aeb@cwi.nl. Report bugs in the program
to fileutils-bugs@gnu.ai.mit.edu.
GNU fileutils 4.0 November 1998 9