LS
Section: User Commands (1)
Updated: August 1998
NAME
ls, dir, vdir - list directory contents
SYNOPSIS
ls [options] [file...]
POSIX options:
[-CFRacdilqrtu1]
GNU options (shortest form):
[-1abcdfgiklmnopqrstuxABCDFGLNQRSUX]
[-w cols]
[-T cols]
[-I pattern]
[--full-time]
[--format={long,verbose,commas,across,vertical,single-column}]
[--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
arguments, 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 current 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 multicolumn
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 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.
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 modification time
for sorting (with -t) or listing (with -l).
- -1
-
For single-column output.
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'; that is, files are by default listed
in columns, sorted vertically.
vdir
(also installed as
v)
is equivalent to `ls -l'; 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 when standard output is
not a terminal.
- -a, --all
-
List all files in directories, including all files that start with `.'.
- -b, --escape
-
Quote nongraphic characters in file names using alphabetic and octal
backslash sequences like those used in C.
- -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 whatever order they are
stored on the disk.
Also enables
-a
and disables
-l,
--color,
and
-s
if they were specified before the
-f.
- -g
-
Ignored; for Unix compatibility.
- -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 kilobytes.
- -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 timestamp contains the year
instead of the time of day.
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 corresponding 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-executable 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
-
Append a character to each file name indicating the file type. This is like
-F
except that executables aren't marked.
- -q, --hide-control-chars
-
Print question marks instead of nongraphic characters in file names. This
is the default.
- -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.
- -w, --width cols
-
Assume the screen is
cols
columns wide. The default is taken from the terminal driver if
possible; otherwise the environment variable
COLUMNS
is used if it is set; otherwise the default is 80.
- -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 additional 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, without fancy searching.
If directories are being listed recursively
(-R),
output a similar line after each subdirectory:
//SUBDIRED//
BEG1 END1 ...
- -F, --classify, --file-type
-
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 format directory listing.
- -I, --ignorepattern
-
Do not list files whose names match the shell pattern
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 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
-
Enclose file names in double quotes and quote nongraphic 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.
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 whatever order they are
stored on the disk. (The difference between
-Uand-f
is that the former doesn't disable or enable options.) This is especially
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.
- --color[=when]
-
Specify whether to use color for distinguishing file types.
Colors are specified using the LS_COLORS environment variable.
For information on how to set this variable, see
dircolors(1).
when
may be omitted, or one of:
-
- none
-
Do not use color at all. This is the default.
- auto
-
Only use color if standard output is a terminal.
- 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.
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 determines 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_MESSAGES 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.
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-3.16 package;
other versions may differ slightly. Mail corrections and additions to
aeb@cwi.nl and aw@mail1.bet1.puv.fi and ragnar@lightside.ddns.org .
Report bugs in the program to fileutils-bugs@gnu.ai.mit.edu.