ls - list directory contents

ls is used to obtain detailed information on files and directories. The type, scope and output format of the displayed information can be specified by setting various options.

Syntax

ls [ option]...[ file]...

No argument specified

ls lists the names of files and directories in the current working directory. The output is sorted in alphabetical order.

No option specified

file is a directory:
ls lists the names of the files and directories in it using a single-column output format. The output is sorted in alphabetical order. The only files not listed are those which begin with a dot, such as .profile.

file is a file:
ls displays the name of the file. You can use a partially qualified file name. If an asterisk (*) is specified for file, all files and directories (and their contents) are listed.

-a

Lists all file names, including those that begin with a dot.

-b

Non-printing characters in file names are represented in the octal notation \ddd, where ddd is the octal value of the character (see Tables and directories, EBCDIC character set).

-c

Together with option -l
Lists time of last modification of the inode (file created, mode change, etc.) instead of the time at which the file was last modified.

Together with option -t:
ls uses the time of last modification of the inode as the sort criterion instead of the time of last modification of the file.

-C

Multi-column output with entries sorted down the columns in alphabetical order. The default is one entry per line of output.

ls uses the environment variable COLUMNS to determine the number of character positions per line. If this variable is not set, the value of the environment variable TERM is checked in the terminfo database in order to determine the number of columns. If this information cannot be obtained, 80 characters per line are assumed.

-d

If file is a directory, ls lists its name (not its contents). This option is often used together with -l in order to obtain information on the status of the directory. If file is omitted, ls outputs a period for the current directory. 

-f

Forces each argument to be interpreted as a directory and lists the entries of each directory in the order in which they appear. If no argument is specified, the entries in the current directory are listed. This option turns on the -a option and turns off options -l, -t, -F, -s and -r.

-F

Puts a slash (/) after each file name if the file is a directory, an asterisk (*) if the file is declared as an executable, a commercial at symbol (@) if the file is a symbolic link, a vertical bar | if it is a FIFO file.

-g

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

-i

Prints the unique identification number (inode number) for each file in the first column of the report.

-l

A list of detailed information is provided in long format for each file.

This information is displayed as shown below:

-rwxrwxrwx n name gruppe nnnn Mon nn nn:nn datei
||         | |    |      |    |   |  |     |
||         | |    |      |    |   |  |     Dateiname
||         | |    |      |    |   |  Uhrzeit
||         | |    |      |    |   Tag
||         | |    |      |    Monat
||         | |    |      Größe in Byte
||         | |    Gruppenname
||         | Benutzerkennung des Eigentümers
||         Anzahl der Verweise
|Zugriffsrecht
Identifikation

Identification

d for a directory

l for a symbolic link

b for a block special file

c for a character special file

m for a shared data (memory) file

p for a FIFO file (named pipe)

s for a semaphore

- for an ordinary file

Access permissions

3 sets of 3 characters each provide information on the permissions of

• the file owner (characters 1 to 3),

• users belonging to the same group (characters 4 to 6),

• other users (characters 7 to 9).

Each set uses the following codes:

Position 1:

r for read permission or - for no read permission.

Position 2:

w for write permission or - for no write permission.

Position 3:

x for execute permission

s for execute permission with s bit set

t for execute permission with t bit (sticky bit) set

T for no execute permission with t bit (sticky bit) set

S for the l bit (set-user-ID bit set, execute permission not set)

- for no execute permission with no special bit set

If the s bit (set-user-ID mode) is set for the owner or the group and the corresponding x bit (execute permission) is also set, the x will be replaced by an s. The s bit cannot be set without the corresponding x bit.

In the case of group permissions, an S may occupy the position of the x bit if the l bit is set for the file, i.e. if mandatory locking has been enabled for the file. Neither the x bit nor the s bit can be set for the group in this case.
If the l bit is set for a file, a program using the lockf() function can lock read and write access to the file for as long as it is accessing that file (see chmod).

For others permissions, the position of the x bit may be occupied by a t or T. These refer to the state of the sticky bit (t bit): t stands for set sticky bit with x bit, T for set sticky bit without x bit (see chmod).

Number of links
Decimal number indicating the number of links to the file; at least 1.

Login of owner
Login name of the file owner.

Group name
Group name of the file owner.

Size in bytes
Decimal number that indicates the file size in bytes.
If a special file is listed, the major device number and the minor device number are displayed instead of the file size.

Month, day, time
Indicates the date and time of the last modification to the file. If the last modification was made more than six months ago, the year is output instead of the time.

File name
Name of the file.

In the case of directories, the size of the entire directory is displayed in addition to the individual file sizes. This size is specified in 512-byte blocks (see Example 4).

If the file or directory is a symbolic link, the file name is printed followed by an arrow ’->’ and the pathname of the referenced file.

Note that in a Remote File Sharing environment, you may not always have the permissions indicated by the output of the ls -l command.

-L

With symbolic links, the link name is listed rather than the name of the original file or directory.

Example

$ ls -l
-rw------- 1   HUGO     other       7593   Nov 30 10:48 file
-rw------- 1   HUGO     other          3   Dec 17 10:53 linker -> file
$ ls -lL
-rw------- 1   HUGO     other       7593   Nov 30 10:48 file
-rw------- 1 HUGO other 7593 Nov 30 10:48 linker

-m

Lists files across the page (stream output format), separated by commas. ls uses an environment variable, COLUMNS, to determine the number of character positions per line. If this variable is not set, the value of the environment variable TERM is checked in the terminfo database in order to determine the number of columns. If this information cannot be obtained, 80 columns are assumed per line.

-n

Same effect as -l, except that the user ID and the group ID are displayed instead of the login and group names.

-o

Same effect as -l, except that the group is not displayed.

-p

Puts a slash (/) after each file name if the file is a directory.

-q

Non-printing characters in file names are represented by question marks.

-r

Reverses the sorting order.

-s

Prints the size of each file in column 1 (in 512-byte blocks) in addition to the file names.

-t

Sorts by time last modified instead of by file name (latest first).

-u

Together with option -t
Uses the time of last access as the sort criterion.

Together with option -l
The time of last access is displayed instead of the time of last modification.

-x

Multi-column output with entries sorted across instead of down the page. ls uses the environment variable, COLUMNS, to determine the number of character positions per line. If this variable is not set, the value of the environment variable TERM is checked in the terminfo database in order to determine the number of columns. If this information cannot be obtained, 80 characters per line are assumed.

-1

Prints only one entry per line of output.

file

Name of the file or directory for which you want information to be listed. You can also name more than one file or directory.

file not specified:
The contents of the current directory will be listed.

File

/etc/group

Contains all the groups that have been set up.

Variable

COLUMNS

Determine the user’s preferred column position width for writing multiple text-column output. If this variable contains a string representing a decimal integer, the ls utility calculates how many pathname text columns to write (see -C) based on the width provided. The column width chosen to write the names of files in any given directory will be constant. Filenames will not be truncated to fit into multiple text-column output.

TZ

Determine the timezone for date and time strings written by ls.

Locale

The following environment variables affect the execution of ls:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_COLLATE

Determine the collating sequence of the output from ls.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments). It determines which characters are defined as non-printing characters in conjunction with the -q option.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example 1

Listing the contents of the current directory in long format.
User’s login name: HUGO.

$ ls -l
total 142
drwx--x--x 2   HUGO     other         48   Dec  1 16:13 ADDRESSES
-rw------- 1   HUGO     other        356   Dec 17 13:58 card_a
-rw------- 1   HUGO     other      24802   Dec  1 12:13 card_b
-rw------- 1   HUGO     other       7890   Nov 30 10:48 card_c
-rwx--xr-x 1   HUGO     other       7253   Dec 21 13:37 card_d
-rw------- 1   HUGO     other       9476   Dec 21 13:37 card_e
-rwx--x--x 1   HUGO     other          0   Dec 18 13:16 card_f
-rw------- 1   HUGO     other        593   Nov 30 10:48 letter1
-rw------- 1   HUGO     other        837   Dec 17 10:53 letter2
-rw------- 1   HUGO     other       3247   Dec 17 13:46 letter3
-rw------- 1   HUGO     other       5222   Nov 30 10:48 letter4
-rw-rw-rw- 1   HUGO     other       4687   Dec 21 11:15 letter5
-rw------- 1   HUGO     other        228   Nov 30 10:48 letter6
-r-------- 1   HUGO     other        105   Dec 21 13:39 typescript

Example 2

Multi-column output of the current directory using a line width of 80 columns per line. (This output form is also the default for terminal output).

$ ls -C
ADDRESSES   card_c      card_f      letter3     letter6
card_a      card_d      letter1     letter4     typescript
card_b      card_e      letter2     letter5

Example 3

Multi-column output after defining the line width as 40 columns per line.

$ COLUMNS=40
$ export COLUMNS
$ ls -C
ADDRESSES   card_e      letter4
card_a      card_f      letter5
card_b      letter1     letter6
card_c      letter2     typescript
card_d      letter3

Example 4

Listing the current directory in long format (option -l), marking directories (option -p) and including all files that begin with a period (option -a).
User’s login name: sisyphus.

$ ls -pla
total 120
drwxr-xr-x  10 SISYPHUS   other       5720   Nov 17 08:00 ./
drwxr-xr-x  13 SYSROOT    root        3380   Nov 04 11:48 ../
-rw-------   1 SISYPHUS   other         79   Jul 19 14:21 .profile
-rw-------   1 SISYPHUS   other         14   Oct 21 08:56 .rhosts
-rwx------   1 SISYPHUS   other        125   May 25 10:29 begin
drwx--x--x   2 SISYPHUS   other       3380   Nov 09 10:30 commands/
drwx------   2 SISYPHUS   other       1820   Oct 11 15:35 letters/
drwxr-----   3 SISYPHUS   other       2340   Oct 11 15:35 lingua/
-rw-------   1 SISYPHUS   other       2082   Nov 08 12:29 ls.ex
-rw-------   1 SISYPHUS   other      11597   Nov 17 07:59 ls.rc.1
-rw-------   1 SISYPHUS   other       1351   Jul 19 15:14 plural
drwx------   2 SISYPHUS   other       3380   Oct 11 15:36 post/
drwx------   2 SISYPHUS   other       1560   Oct 11 15:36 pro/
drwx--x--x   2 SISYPHUS   other       2080   Nov 07 10:43 proc/
drwx------   2 SISYPHUS   other       1560   Oct 11 15:36 screens/
drwx--x--x   2 SISYPHUS   other       1040   Nov 15 08:23 sdg/

Example 5

List all files and directories (and their contents). Each directory name is followed by a colon.

$ ls -C *
Mailboxes  authors   bvp.col
lingua:
car.cdr    engl.ger  examples  terms
screens:
out        pause     sinix

See also

chmod, find, ln