LS(1)

NAME
ls, dir, vdir - list contents of directories

SYNOPSIS
ls [-abcdfgiklmnopqrstuxABCFGLNQRSUX1] [-w cols] [-T cols] [-I pattern] [--all] [--escape] [--directory] [--inode] [--kilobytes] [--numeric-uid-gid] [--no-group] [--hide-control-chars] [--reverse] [--size] [--width=cols] [--tabsize=cols] [--almost-all] [--ignore-backups] [--classify] [--file-type] [--full-time] [--ignore=pattern] [--dereference] [--literal] [--quote-name] [--no-color] [--7bit] [--8bit] [--recursive] [--sort={none,time,size,extension}] [--format={long,verbose,commas,across,vertical,single-column}] [--time={atime,access,use,ctime,status}] [--help] [--version] [path...]

DESCRIPTION
This manual page documents the GNU version of ls. dir and vdir are versions of ls with different default output formats. These programs list each given file or directory path. Directory contents are sorted alphabetically. For ls, files are by default listed in columns, sorted vertically, if the standard output is a terminal; otherwise they are listed one per line. For dir, files are by default listed in columns, sorted vertically. For vdir, files are by default listed in long format.

  OPTIONS

-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 instead of the modification time. If the long listing format is being used, print the status change time instead of the modification time.

-d, --directory
    List 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. The same as enabling -a and -U and disabling -l, -s, and -t.

--full-time
    List times in full, rather than using the standard abbreviation heuristics.

-g  Ignored; for Unix compatibility.

-i, --inode
    Print the index number of each file to the left of the file name.

-k, --kilobytes
    If file sizes are being listed, print them in kilobytes. This overrides the environment variable POSIXLY_CORRECT.

-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.

-m, --format=commas
    List files horizontally, with as many as will fit on each line, separated by commas.

-n, --numeric-uid-gid
    List the numeric UID and GID instead of the names.

-o, --no-color
    Do not colorize the names of files using ISO 6429 (ANSI) color control sequences depending on the file type and/or the extension. See `DISPLAY COLORIZATION' below.

-p  Append a character to each file name indicating the file type.

-q, --hide-control-chars
    Print question marks instead of nongraphic characters in file names.

-r, --reverse
    Sort directory contents in reverse order.

-s, --size
    Print the size of each file in 1K blocks to the left of the file name. If the environment variable POSIXLY_CORRECT is set, 512-byte blocks are used instead.

-t, --sort=time
    Sort directory contents by timestamp 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. If the long listing format is being used, print the last access time instead of the modification time.

-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.

-F, --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 format directory listing.

-L, --dereference
    List the files linked to by symbolic links instead of listing the contents of the links.

-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.

-U, --sort=none
    Do not sort directory contents; list them in whatever order they are stored on the disk. This option is not called -f because the Unix ls -f option also enables -a and disables -l, -s, and -t. It seems useless and ugly to group those unrelated things together in one option. Since this option doesn't do that, it has a different name.

-X, --sort=extension
    Sort directory contents alphabetically by file extension (characters after the last `.'); files with no extension are sorted first.

-1, --format=single-column
    List one file per line.

-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.

-T, --tabsize cols
    Assume that each tabstop is cols columns wide. The default is 8.

-I, --ignore pattern
    Do not list files whose names match the shell pattern pattern 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.

--help
    Print a usage message on standard output and exit successfully.

--version
    Print version information on standard output then exit successfully.

  DISPLAY COLORIZATION
This version of ls can produce color output. The global defaults are found in the file /etc/DIR_COLORS. Users can also create a copy of this file in their home directory called $HOME/.dir_colors to store their own preferences. The file contains color sequences for the basic files types, executables, and files with certain extensions such as '.gz' or '.tar'. The sequences are, in order: plaintext, normal file, directory, symbolic link, FIFO, socket, block device, character device, and executable file. The first sequence (plaintext) is the one applied to the end of each file name in order to restore normal text output. This is usually, but not always, a zero (0). A single color sequence is composed of numerical commands separated by semicolons. The most common commands are:
 0 to restore default color
 1 for brighter colors
 4 for underlined text
 5 for flashing text
30 for black foreground
31 for red foreground
32 for green foreground
33 for yellow (or brown) foreground
34 for blue foreground
35 for purple foreground
36 for cyan foreground
37 for white (or gray) foreground
40 for black background
41 for red background
42 for green background
43 for yellow (or brown) background
44 for blue background
45 for purple background
46 for cyan background
47 for white (or gray) background

Not all commands work on all systems or display devices.

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, it 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.

TODO
Colorizations and character set selection need to be more system independent. Using the colorization option disables the use of the tab character for column spacing unless the -T option is used; apparently some systems don't like tabs and colors in conjunction.