ls(C)

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

Synopsis

ls [-AabCcdeFfgiLlmnopqRrstux1] [ -Ws |-Wv ] [file . . . ] -Ws |-Wv

l [-AabCcdeFfgiLnopqRrstux1] [ -Ws |-Wv ] [file . . . ] -Ws |-Wv

lc [-AabcdeFfgiLnopqRrstux1] [ -Ws |-Wv ] [file . . . ] -Ws |-Wv

lf [-AabcdefgiLnopqRrstux1] [ -Ws |-Wv ] [file . . . ] -Ws |-Wv

lr [-AabcdeFfgiLnopqrstux1] [ -Ws |-Wv ] [file . . . ] -Ws |-Wv

lx [-AabCcdeFfgiLnopqrstu1] [ -Ws |-Wv ] [file . . . ] -Ws |-Wv

Description

For each directory argument, ls lists the contents of the directory; for each file argument, ls repeats its name and any other information requested. The output is sorted alphabetically by default. When arguments are not given, the current directory is listed. When several arguments are given, the arguments are first sorted appropriately, but file arguments appear before directories and their contents. ls processes supplementary code set characters according to the locale specified in the LC_CTYPE and LC_COLLATE environment variables (see LANG on environ(M)) except as noted under the -b, -q, and -S options below.

The remaining commands are synonyms of ls with particular options. They are provided for compatibility with previous implementations. Specifying a redundant options of ls does with one of of these commands (for example, -F with lf) does not cause an error.

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

lc lists files in columns by default. This command is equivalent to ls -C.

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. This command is equivalent to ls -F.

lr lists files, recursively listing any subdirectories encountered. lr is a variant of lc, so files are listed in columns by default. This command is equivalent to ls -R.

lx, another variant of lc, lists files in columns, but sorted across the page rather than down the page. This command is equivalent to ls -x.

There are three major listing formats. The default format for output directed to a terminal is multi-column with entries sorted down the columns. The options -C and -x enable multi-column formats; and the -m option enables stream output format, in which files are listed across the page, separated by commas.

To determine output formats for the -C, -x, and -m options, ls uses an environment variable, COLUMNS, to determine the number of positions available on one output line. If this variable is not set, the terminfo database is used to determine the number of columns, based on the environment variable TERM. If this information cannot be obtained, 80 columns are assumed.

The ls command has the following options:

-1

Print one entry per line of output. This is the default format.

-A

List all entries. Entries whose name begin with a dot (.) are listed. This option does not list current directory ``.'' and directory above ``..''. When ls is invoked by the root account, this is the default.

-a

List all entries, including those that begin with a period (.), which are normally not listed.

-b

Force printing of non-printable characters to be in the octal \ddd notation. All multibyte characters are considered printable.

-C

Multi-column output with entries sorted down the columns.

-c

Use time of last modification of the i-node (file created, mode changed, and so on) for sorting (-t) or printing (-l).

-d

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

-e extent_opt

Specify how to handle a vxfs file that has extent attribute information. Extent attributes include reserved space, a fixed extent size, and extent alignment. It may not be possible to preserve the information if the destination file system does not support extent attributes, has a different block size than the source file system, or lacks free extents appropriate to satisfy the extent attribute requirements. Valid values for extent_opt are:

warn: Issue a warning message if extent attribute information cannot be kept (default).
force: Fail the copy if extent attribute information cannot be kept.
ignore: Ignore extent attribute information entirely.

When used with -l, -e displays extent attribute information for files with reserved space or fixed extent sizes.

-F

Put a slash (/) after each filename if the file is a directory, an asterisk (

) if the file is executable, a vertical bar (|) if it is a FIFO, and an at sign (@) if the file is a symbolic link.

-f

Force each argument to be interpreted as a directory and list 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.

-g

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

-i

For each file, print the i-node number in the first column of the report.

-L

When listing status, if an argument is a symbolic link, list the status of the file or directory referenced by the link rather than that of the link itself.

-l

List in long format, giving mode, number of links, owner, group, size in bytes, and date and time of last modification for each file. 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.

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.

The date is given in the locale specified by the LC_TIME environment variable. If the file is a special file, the size field contains the major and minor device numbers rather than a size. If the file is a symbolic link, the filename is printed followed by ``->'' and the pathname of the referenced file.

-m

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

-n

The same as -l, except that the owner's UID and group's GID numbers are printed, rather than the associated character strings.

-o

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

-p

Put a slash (/) after each filename if the file is a directory.

-q

Force printing of non-printable characters in file names as the character question mark (?). All multibyte characters are considered printable.

-R

Recursively list subdirectories encountered.

-r

Reverse the order of sort to get the reverse of the locale's collation sequence or oldest first as appropriate.

-S

This option causes the sort order of listed files to use the collating sequence specified by the LC_COLLATE environment variable. By default, the collating sequence of the "C" locale is used.

-s

Give size in blocks, including indirect blocks, for each entry. Since vxfs allocates extents, a copied file or a file retrieved from an archive may or may not need the same number of indirect address extents as the original file; thus the blocks reported by this option may be different. The size and contents of the file, however, are identical.

-T

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

   Aug 31 09:37:00 2001

-t

Sort by time stamp (latest first) then by name. The default is the last modification time. (See -n and -c.)

-u

Use time of last access instead of last modification for sorting (with the -t option) or printing (with the -l option).

-x

Multi-column output with entries sorted across rather than down the page.

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

The mode printed under the -l option consists of eleven possible characters. The first character may be one of the following:

d: if the entry is a directory;
l: if the entry is a symbolic link;
b: if the entry is a block special file;
c: if the entry is a character special file;
m: the entry is XENIX shared data (memory) file;
p: if the entry is a fifo (named pipe) special file;
s: the entry is a XENIX semaphore;
-: if the entry is a regular file.

The next 9 characters are interpreted as three sets of three bits each. The first set refers to the owner's permissions; the next to permissions of others in the user-group of the file; and the last to all others. Within each set, the three characters indicate permission to read, write, and execute the file as a program, respectively. For a directory, ``execute'' permission is interpreted to mean permission to search the directory for a specified file.

The last character indicates whether an Access Control List (ACL) exists for the file. If an ACL exists, the last character is a plus sign (+); if an ACL does not exist, there is no character printed. ACLs are supported only if the file system is of type sfs or vxfs.

ls -l (the long list) prints its output as follows:

   -rwxrwxrwx  1 smith  dev    10876  May 16 9:42 part2

Reading from right to left, you see that the current directory holds one file, named part2. Next, the last time that file's contents were modified was 9:42 A.M. on May 16. The file contains 10,876 bytes. The owner of the file, or the user, belongs to the group dev (perhaps indicating ``development''), and their login name is smith. The number, in this case 1, indicates the number of links to file part2 (see cp(C)). Finally, the dash and letters tell you that user, group, and others have permissions to read, write, and execute part2. Note also that an ACL does not exist for part2.

The execute (x) symbol here occupies the third position of the three-character sequence. A - in the third position would have indicated a denial of execution permissions.

The permissions are indicated as follows:

r: the file is readable
w: the file is writable
x: the file is executable
-: the indicated permission is not granted
l: mandatory locking occurs during access (the set-group-ID bit is on and the group execution bit is off); if the POSIX2 environment variable is set, s is printed instead of l
s: the set-user-ID or set-group-ID bit is on, and the corresponding user or group execution bit is also on
S: undefined bit-state (the set-user-ID bit is on and the user execution bit is off)
t: the 1000 (octal) bit, or sticky bit, is on (see chmod(C)), and execution is on
T: the 1000 bit is turned on, and execution is off (undefined bit-state)

For user and group permissions, the third position is sometimes occupied by a character other than x or -. s also may occupy this position, referring to the state of the set-ID bit, whether it be the user's or the group's. The ability to assume the same ID as the user during execution is, for example, used during login when you begin as root but need to assume the identity of the user you login as.

In the case of the sequence of group permissions, l may occupy the third position. l refers to mandatory file and record locking. This permission describes a file's ability to allow other files to lock its reading or writing permissions during access.

For other permissions, the third position may be occupied by t or T. These refer to the state of the sticky bit and execution permissions.

The -e option (used with -l) displays extent attribute information as follows:

-rwxrwxrwx 1 smith dev 10876 May 16 9:42 part2 :res 36 ext 3 align noextend

This output line indicates a file with 36 blocks of reservation, a fixed extent size of 3 blocks, all extents aligned to 3 block boundaries, and the file unable to be grown once the current reservation is exhausted.

The format of the date given in the long listing is dependent on the environment variable LC_TIME (the examples are in the C locale). (See LANG on environ(M).)

Files

/etc/passwd: user IDs for ls -l and ls -o
/etc/group: group IDs for ls -l and ls -g
/usr/share/lib/terminfo/?/: terminal information database
/usr/lib/locale/locale/LC_MESSAGES/uxcore.abi: language-specific message file (see LANG on environ(M)).

Examples

Some examples of file permissions:

-rwxr--r--

Readable, writable, and executable by the user and readable by the group and others.

-rwsr-xr-x

Readable, writable, and executable by the user, readable and executable by the group and others, and allows its user-ID to be assumed, during execution, by the user presently executing it.

-rw-rwl---

Readable and writable only by the user and the group and can be locked during access.

-rwxr-xr--+

An example of a file that has an ACL. This describes a file that is readable, writable, and executable by the user, at most readable and executable by the file group class entries, and readable only by all others. The individual ACL entries may further restrict access for individual users and/or groups.

If an ACL exists for a file, the permissions (also referred to as the base permission mode) represent the maximum permissions to the file, that is, ACL entries may further restrict access to the file.

The complete ACL, representing the actual permissions to the file, can be displayed using the getacl command.

The ls -a command prints the names of all files in the current directory, including those that begin with a dot (.), which normally do not print.

The ls -aisn command provides information on all files, including those that begin with a dot (-a), the i-number -- the memory address of the i-node associated with the file -- printed in the left-hand column (-i); the size (in blocks) of the files, printed in the column to the right of the i-numbers (-s); finally, the report is displayed in the numeric version of the long list, printing the UID (instead of user name) and GID (instead of group name) numbers associated with the files.

When the sizes of the files in a directory are listed, a total count of blocks, including indirect blocks, is printed.

References

chmod(C), find(C), getacl(C), setacl(C)

Notices

Unprintable characters in file names may confuse the columnar output options.

The total block count will be incorrect if there are hard links among the files.

The -R option has been multithreaded and is implemented via nftw (walk a file tree).

This command has been updated to handle files greater than 2GB.