ls(C)

ls, l, lc, lf, lr, lx -- list contents of directories

Syntax

ls [ -1ACFLRTabcdfgilmnopqrstux ] [ -Ws | -Wv ] [ directory | file ... ]

l [ -ACFLRTabcdfginopqrstu ] [ -Ws | -Wv ] [ directory | file ... ]

lc [ -1AFLRTabcdfgilmnopqrstux ] [ -Ws | -Wv ] [ directory | file ... ]

lf [ -1ALRTabcdfgilmnopqrstux ] [ -Ws | -Wv ] [ directory | file ... ]

lr [ -1AFLTabcdfgilmnopqrstux ] [ -Ws | -Wv ] [ directory | file ... ]

lx [ -1ACFLRTabcdfgilmnopqrstu ] [ -Ws | -Wv ] [ directory | file ... ]

Description

l, lc, lf, lr, ls, and lx make up the ls family of commands.

For each directory, the contents are listed. For each file, the filename is repeated and any other requested information is displayed. By default, the output is sorted alphabetically. When no argument is given, the current directory is listed. When several arguments are given, they are sorted appropriately; file arguments are processed before directories and their contents.

l provides a long listing, one file per line, by default. If a file is a symbolic link, l displays the inode information of the file at the end of the chain, and appends ``@'' to the name of the symbolic link. This command is equivalent to ls -Ws.

lc lists files in columns by default.

lf lists files, indicating directories, executables, symbolic links and named pipes (or FIFOs). lf is a variant of lc, so files are listed in columns by default.

lr lists files, recursively listing any subdirectories encountered. lr is a variant of lc, so files are listed in columns by default.

ls lists files alphabetically, one entry per line, by default.

lx, another variant of lc, lists files in columns, but sorted across the page rather than down the page.

You can also list files in stream (across the page) output format, separated by commas, using ls -m.

ls determines the output format for the -C (lc), -x (lx), and -m options by using an environment variable, COLUMNS, to determine the number of character positions available on one output line. If this information cannot be obtained, 80 columns are assumed.

Each of these programs is a link to ls; depending on the name by which it is invoked, the program behaves as if certain options are set. lc is equivalent to ls -C, lf is equivalent to ls -F, lr to ls -R, lx to ls -x, and l to ls -l. Specifying the equivalent option when invoking a link to ls has no effect.

Options are:

-1

Forces an output format with one entry per line, for lc, lf, lr, and lx.

-a

Lists all entries; ``.'' and ``..'' are not suppressed.

-A

Lists all entries. Entries whose name begin with a dot (.) are listed. This option does not list current directory ``.'' and directory above ``..''.

-b

Forces printing of non-graphic characters in the \ddd notation, in octal.

-c

Uses the last time that the file was changed for sorting. The change time refers to modification of the file's data, modification of the information stored in the inode, or creation of the file.

This option is used with -t option.

-C

Lists in columns with entries sorted down the columns. If the argument(s) are filename(s), output is across the page, rather than down the page in columns.

-d

If an argument is a directory, lists only its name (not its contents); often used with -l to get the status of a directory.

-f

Forces each argument to be interpreted as a directory and lists the name found in each slot. This option turns off -l, -t, -s, and -r, and turns on -a. The order is the order in which entries appear in the directory.

-F

Causes directories to be marked with a trailing ``/'', executable files to be marked with a trailing ``

'', symbolic links to be marked with a trailing ``@'', and named pipes (or FIFOs) to be marked with a ``|''.

-g

The same as -l, except that the owner is not printed.

-i

For each file, prints the inode number in the first column of the report.

-l

Lists in long format, giving mode, number of links, owner, group, size in bytes, the time that each file was last modified. The -1 option is assumed. For files less than six months old, minutes and seconds are included in the modification time and the year is excluded. For a consistent format, use -T.

-T

Similar to -l, except that the modification time is always displayed in full, as in this example:

   Aug 31 09:37:00 2001

Unless one of the -c or -u options is specified, the modification time refers only to changes made to the file's data, or the creation of the file. It does not record the time that changes were made to the information stored in the inode.

If the file is a symbolic link, the filename is printed followed by ``->'' and the pathname of the referenced file.

If the file is a special file, the size field will contain the major and minor device numbers, rather than a size. A total count of blocks in the directory, including indirect blocks, is printed at the top of long format listings.

A description of the mode listing is given in ``File modes''.

-L

If an argument is a symbolic link, lists the information for the file or directory the link references.

-m

Forces stream output format; files are listed across the page, separated by commas.

-n

The same as -l, except that the user ID (UID) and group ID (GID) numbers are printed, rather than the owner name and the group name.

-o

The same as -l, except that the group is not printed.

-p

Puts a slash (/) after each directory.

-q

Displays non-printable characters and tabs in filenames as the character ``?''.

-r

Reverses the order of sort to get reverse alphabetic or oldest first, as appropriate.

-R

Recursively lists arbitrarily deep subdirectories.

-s

Gives size in 512-byte blocks, including indirect blocks, for each entry.

-t

Sorts by time modified (latest first) instead of by name. Files with equivalent modification times are then sorted alphabetically. The modification time sorted on depends on whether the -c, or -u option is also specified.

-u

Uses the time that the file was accessed for sorting. The access time refers to the last time that the file's data was read, or the creation of the file. It does not record the time that changes were written to the file's data, or to the information stored in the inode.

This option is used with the -t option.

-Ws

Prints a long listing similar to that obtained using the -l option. If the file is a symbolic link, this option displays the inode details of the file at the end of the symbolic link chain, and appends an ``@'' to the name of the symbolic link.

-Wv

Prints a long listing similar to that obtained using the -l option. If the file is the start of a chain of symbolic links, this option displays the inode details of the file at the end of the chain, and prints the pathnames of all files in the chain separated by ``->'' symbols.

-x

Lists in columns with entries sorted across, rather than down, the page. If the argument(s) are filename(s), output is across the page, rather than down the page in columns.

File modes

The mode printed using the -l (long listing) option to ls or the l command consists of a string of 10 characters. The first character indicates the file type:

-: Ordinary file.
d: Directory.
l: Symbolic link.
b: Block special device file.
c: Character special device file.
p: Named pipe.
s: Semaphore.
m: Shared data (memory) file.

The next 9 characters are the permissions which show who can access the file. Permissions are in 3 sets of 3 bits each. The first set refers to the owner permissions; the second set to the group permissions; and the third set to permissions for all other users. Within each set, the three characters indicate permission to read, to write, or to execute the file, respectively.

The permissions are as follows:

r: Read.
w: Write.
x: Execute; on a directory, this gives search permission.
s: Setuid, setgid: set the UID or GID of the executing process to that of the file when the file is executed.
S: Setuid/setgid is set, but the underlying execute permission is not set.
t: The sticky bit is set. If the file is a directory, files in the directory can only be removed by their owners, or by root. If the file is an executable file, a pointer to the text segment of the file will be retained in memory after the file is executed. This enables the system to load the file faster if it is executed again.
T: The sticky bit (t bit) is set, but the underlying execute permission is not set.
-: No permission is set.

See chmod(C) for more information about permissions.

Exit values

ls returns the following values:

0: all files were written successfully
>0: an error occurred

Examples

To list ordinary files in the current directory, with full information including details of files pointed to by symbolic links:

l

To list all files (including hidden files):

ls -al

To obtain a listing of all files in all subdirectories of /tmp, printed in columns with entries sorted across the page, executables highlighted with an asterisk, and directories indicated with a slash:

lf -xR /tmp

Limitations

ls sorts according to the collating sequence defined by the locale.

Newline and tab are considered printing characters in filenames.

Unprintable characters in filenames may confuse the columnar output options.

ls -s interprets one 1024-byte block (a standard SCO OpenServer block) as two of its own 512-byte blocks. Thus a 500-byte file is interpreted as two blocks rather than one.

The -Wv option may display incorrect file details if an intermediate link in a chain of symbolic links contains a relative pathname.

Files

/etc/passwd: database of user IDs
/etc/group: database of group IDs
/etc/termcap: database of terminal information

Standards conformance

l is not part of any currently supported standard; it is an extension of AT&T System V provided by The Santa Cruz Operation, Inc.

ls is conformant with:

ISO/IEC DIS 99452:1992, Information technology Portable Operating System Interface (POSIX) Part 2: Shell and Utilities (IEEE Std 1003.21992);
AT&T SVID Issue 2;
X/Open CAE Specification, Commands and Utilities, Issue 4, 1992.

lc and its variants were developed at the University of California at Berkeley and are used with permission.