NAME

ls, l, ll, lsf, lsr, lsx − list contents of directories

SYNOPSIS

ls [−abcdfgilmnopqrstuxACFHLR1] [names]
l [ls options] [names]
ll [ls options] [names]
lsf [ls options] [names]
lsr [ls options] [names]
lsx [ls options] [names]

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 in ascending collation order by default (see Environment Variables below).  When no argument is 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. 

If you are the user with appropriate privileges, all files except .  and ..  are listed by default. 

There are three major listing formats.  The format chosen depends on whether the output is going to a login device (determined by whether output device file is a tty device), and can also be controlled by option flags.  The default format for a login device is to list the contents of directories in multi-column format, with entries sorted vertically by column.  (When individual file names (as opposed to directory names) appear in the argument list, those file names are always sorted across the page rather than down the page in columns because individual file names can be arbitrarily long.)  If the standard output is not a login device, the default format is to list one entry per line.  The −C and −x options enable multi-column formats, and the −m option enables stream output format in which files are listed across the page, separated by commas.  In order to determine output formats for the −C, −x, and −m options, ls uses an environment variable, COLUMNS, to determine the number of character positions available on each 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 is assumed. 

Options

There are numerous options:

−a List all entries; usually entries whose names begin with a period (.) are not listed. 

−b Force printing of non-graphic characters to be in the octal \ddd notation. 

−c Use time of last modification of the inode (file created, mode changed, etc.) 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. 

−f Force each argument to be interpreted as a directory and list the name found in each slot.  This option disables −l, −t, −s, and −r, and enables −a; the order is the order in which entries appear in the directory. 

−g Same as −l, except that only the group is printed (owner is omitted).  If both −l and −g are specified, the owner is not printed. 

−i For each file, print the inode number in the first column of the report.  When used in multi-column output, the number precedes the file name in each column. 

−l List in long format, giving mode, number of links, owner, group, size in bytes, and time of last modification for each file (see further DESCRIPTION and Access Control Lists below).  If the time of last modification is greater than six months ago, or any time in the future, the year is substituted for the hour and minute of the modification time.  If the file is a special file, the size field contains the major and minor device numbers rather than a size. 

−m Stream output format. 

−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 only the owner is printed (group is omitted).  (If both −l and −o are specified, the group is not printed). 

−p Put a slash (/) after each file name if that file is a directory. 

−q Force printing of non-graphic characters in file names as the character (?). 

−r Reverse the order of sort to get reverse (descending) collation or oldest first, as appropriate. 

−s Give size in blocks, including indirect blocks, for each entry.  The first entry printed is the total number of blocks in the directory.  When used in multi-column output, the number of blocks precedes the file name in each column. 

−t Sort by time modified (latest first) before sorting alphabetically. 

−u Use time of last access instead of last modification for sorting (−t option) or printing (−l option). 

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

−A The same as −a, except that the current directory "." and parent directory ".." are not listed.  For the user with appropriate privileges, this flag defaults to ON, and is turned off by −A. 

−C Multi-column output with entries sorted down the columns.  The −1 option takes precedence over −C. 

−F Put a slash (/) after each file name if that file is a directory or a symbolic link to a directory; put an asterisk (*) after each file name if that file is executable; put an at sign (@) after each file name if that file is a symbolic link to a file. 

−H Put a plus sign (+) after each file name if that file is a hidden directory (context-dependent file).  This option also implies −F.  See cdf(4).

When used with the −l option on device files, the cnode name  (if found in /etc/clusterconf) or cnode ID of the device file is printed following the minor device number.  A cnode ID of zero is used to indicate a device file that can be accessed from any cnode. 

−L If the argument is a symbolic link, list the file or directory to which the link refers rather than the link itself. 

−R Recursively list subdirectories encountered. 

−1 The file names will be listed in single column format regardless of the output device.  This forces single column format to the user’s terminal, overriding the −C option if also selected. 

ls normally is known by several shorthand-version names for the various formats:

l is equivalent to ls −m. 

ll is equivalent to ls −l. 

lsf is equivalent to ls −F. 

lsr is equivalent to ls −R. 

lsx is equivalent to ls −x. 

The shorthand notations are implemented as links to ls. Option arguments to the shorthand versions behave exactly as if the long form above had been used with the additional arguments.

Mode Bits Interpretation (−l option)
The mode printed in listings produced by the −l option consists of 10 characters.  The first character indicates the entry type:

d Directory

b Block special file

c Character special file

l Symbolic link

H Hidden directory (context-dependent file).  Hidden directories are only visible when the −H option has been specified;

p Fifo (also called a “named pipe”) special file

n Network special file

s socket

− Ordinary file. 

The next 9 characters are interpreted as three sets of three bits each which identify access permissions for owner, group, and others as follows:

  __________________ 0400  read by owner (r or −)
|  ________________ 0200  write by owner (w or −)
| |  ______________ 0100  execute (search directory) by owner (x, s, S, or −)
| | |  ____________ 0040  read by group (w or −)
| | | |  __________ 0020  write by group (r or −)
| | | | |  ________ 0010  execute/search by group (x, s, S, or −)
| | | | | |  ______ 0004  read by others (r or −)
| | | | | | |  ____ 0002  write by others (w or −)
| | | | | | | |  __ 0001  execute/search by others (x, t, T, or −)
| | | | | | | | |
r w x r w x r w x

Mode letters are interpreted as follows:

− Permission not granted in corresponding position. 

r Read permission granted to corresponding user class. 

w Write permission granted to corresponding user class. 

x Execute (or search in directory) permission granted to corresponding user class. 

s Execute (search) permission granted to corresponding user class.  In addition, SUID (Set User ID) permission granted for owner, or SGID (Set Group ID) permission granted for group, as indicated by position. 

S Same as s except that execute (search) permission is denied to corresponding user class. 

t (last position only) Execute (search) permission granted to others and “sticky bit” is set (see chmod(2) S_ISVTX description). 

T Same as t except execute (search directory) permission denied to others. 

When an option is specified that results in a listing of directory and/or file sizes in bytes or blocks (such as the −s or −l option), a total count of blocks, including indirect blocks, is also printed at the beginning of the listing. 

Access Control Lists (ACLs)

If a file has optional ACL entries, the −l option displays a plus sign (+) after the file’s permissions.  The permissions shown are a summary representation of the file’s access control list, as returned by stat(2) in the st_mode field.  To list the contents of an access control list, use the lsacl(1) command (see acl(5)).

EXTERNAL INFLUENCES

Environment Variables

If the COLUMNS variable is set, ls uses the width provided in determining positioning of columnar output. 

LC_COLLATE determines the order in which the output is sorted. 

LC_CTYPE determines which characters are classified as non-graphic for the −b and −q options, and the interpretation of single and/or multi-byte characters within file names. 

LC_TIME determines the date and time strings output by the −g,−l,−n and −o options. 

LANG determines the language in which messages (other than the date and time strings) are displayed. 

If LC_COLLATE, LC_CTYPE, or LC_TIME is not specified in the environment or is set to the empty string, the value of LANG is used as a default for each unspecified or empty variable.  If LANG is not specified or is set to the empty string, a default of “C” (see lang(5)) is used instead of LANG.  If any internationalization variable contains an invalid setting, ls behaves as if all internationalization variables are set to “C” (see environ(5)).

International Code Set Support

Single- and multi-byte character code sets are supported. 

RETURN VALUE

ls exits with one of the following values:

0 All input files were listed successfully. 

>0 ls was aborted because errors occurred when accessing files.  The following conditions cause an error:

• Specified file not found. 

• User has no permission to read the directory. 

• Process could not get enough memory. 

• Invalid option specified. 

EXAMPLES

Print a long listing of all the files in the current working directory (including the file sizes).  List the most recently modified (youngest) file first, followed by the next older file, and so forth, to the oldest.  Files whose names begin with a .  are also printed. 

ls -alst

WARNINGS

Setting options based on whether the output is a login (tty) device is undesirable because ls −s is much different than ls −s | lpr.  On the other hand, not using this setting makes old shell scripts that used ls almost inevitably fail. 

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

Access Control Lists

Access control list descriptions in this entry apply only to standard HP-UX operating systems.  If HP MACS software has been installed, access control lists are handled differently.  Refer to HP MACS documentation for information about access control lists in the HP MACS environment. 

DEPENDENCIES

NFS The −l option does not display a plus sign (+) after the access permission bits of networked files to represent existence of optional access control list entries. 

AUTHOR

ls was developed by AT&T, the University of California, Berkeley and HP. 

FILES

/etc/passwd to get user IDs for ls −l and ls −o. 

/etc/group to get group IDs for ls −l and ls −g. 

/usr/lib/terminfo/?/∗ to get terminal information. 

SEE ALSO

chmod(1), find(1), lsacl(1), stat(2), cdf(4), acl(5). 

STANDARDS CONFORMANCE

ls: SVID2, XPG2, XPG3, proposed POSIX.2 FIPS (June 1990)

Hewlett-Packard Company  —  HP-UX Release 8.05: June 1991