Silicon Soul

The ability to view the contents of a directory is a fundamental part of using the GNU/Linux command line. For this task, the ls command is a fitting tool.

Note: If you are not familiar with the GNU/Linux command line interface, review the Conventions page before proceeding.

The ls Command

By default, the ls command displays the contents of the current directory.

amnesia@amnesia:/boot$ ls
config-5.4.0-3-amd64  grub

Often, the current directory value is in your terminal's command prompt (in the example above, the current directory is /boot/), but you can always determine it with the pwd command.

amnesia@amnesia:/boot$ pwd
/boot

You can pass the ls command a specific directory as an argument to view that directory's contents.

amnesia@amnesia:~$ ls '/var'
backups  cache  lib  local  lock  log  mail  opt  run  spool  tmp

Above, the current directory is represented by ~ (which is shorthand for the current user's home directory), but the contents of /var/ is shown.

ls can accept multiple directories as arguments, as well (e.g., ls /tmp/ /var/tmp/).

The ls command has many useful options that enable you to modify the type of content you view and how it is displayed. For example, you can include hidden files (i.e., files that start with a . and are not normally visible) in the ls output by adding the -a option.

amnesia@amnesia:/tmp$ ls -a
.
..
6yDLDkf_SS
.font-unix
.ICE-unix
MN_foZiXYc
pulse-PKdhtXMmr18n
systemd-private-84c40c8cb57c4581be82509de05aabaa-colord.service-P9SBwZ
systemd-private-84c40c8cb57c4581be82509de05aabaa-haveged.service-zQX6xW
systemd-private-84c40c8cb57c4581be82509de05aabaa-htpdate.service-3hzp3E
systemd-private-84c40c8cb57c4581be82509de05aabaa-ModemManager.service-Ne4AET
systemd-private-84c40c8cb57c4581be82509de05aabaa-onion-grater.service-12SXKs
systemd-private-84c40c8cb57c4581be82509de05aabaa-spice-vdagentd.service-1gdiTw
systemd-private-84c40c8cb57c4581be82509de05aabaa-tails-shutdown-on-media-removal.service-DOwUKX
systemd-private-84c40c8cb57c4581be82509de05aabaa-tails-tor-has-bootstrapped-flag-file.service-JIxJa0
systemd-private-84c40c8cb57c4581be82509de05aabaa-tails-wait-until-tor-has-bootstrapped.service-9WAiF3
systemd-private-84c40c8cb57c4581be82509de05aabaa-tor@default.service-5OduxR
systemd-private-84c40c8cb57c4581be82509de05aabaa-upower.service-bOqWqp
.Test-unix
.X11-unix
.XIM-unix

Above, . and .. are shorthand characters that represent the current directory (.) and the current directory's parent directory (..).

The Long Listing

One of the most useful ls options, -l, causes directory contents to be displayed using a long listing format. This enables you to view metadata about file system objects.

amnesia@amnesia:~$ ls -l '/usr/include/'
total 13
-rw-r--r-- 1 root root 4546 Aug 29  2016 clif.h
drwxr-xr-x 2 root root   32 Feb 10 13:08 iproute2
drwxr-xr-x 2 root root   89 Feb 10 13:08 python3.7m
drwxr-xr-x 2 root root   63 Feb 10 13:08 reglib
-rw-r--r-- 1 root root 8186 Feb  2 07:41 sudo_plugin.h
drwxr-xr-x 2 root root    3 Feb 10 13:08 X11

The ls -l command output is dense, so it helps to break it down.

total 13

This represents the total disk allocation for all files in each directory listed in the current directory. The unit is given in blocks (a GNU/Linux file system consists of a pool of data blocks into which data is stored), and for this example is 13.

-

The first character in the long listing for an object represents the object's type. These are the possible values:

• - Regular file
• b Block device file
• c Character device file
• d Directory
• l Symbolic link
• n Network file
• p FIFO (First In, First Out; a named pipe)
• s Socket

rw-r--r--

The next nine characters are the object's permission trios, which represent the permissions for the object's User Owner, Group Owner, and Other. The possible values are:

• r Permission to read
• w Permission to write
• x Permission to execute
• s Special Bit Permission (SUID and SGID)
• t Sticky Bit Permission

A - for a permissions bit means no permissions.

After the permission trios, you may see a . or a +, which are related to SELinux and ACLs (Access Control Lists), respectively. However, these are not present in the output above.

1

The next value in the long listing output is the object's reference counter, 1. This value represents how many file system references there are to this object, i.e., how many hard links.

root root

After the reference counter are the object's User Owner and Group Owner, in this case, both root.

4546

After the User Owner and Group owner is the size of the object, in bytes.

Aug 29 2016

The penultimate value in an object's long listing is its last modification date.

clif.h

The final value in an object's long listing is its name.

Options

Here is a summary of some of ls's most useful options:

-a

Display hidden files too.

-d

Display listing for directory itself, instead of its contents.

-h

Display in human-readable format.

-H

Similar to -L, but only works for symbolic links given as arguments.

-i

View inode information.

-l

Use long listing format (used to view object metadata).

-L

Always resolve symbolic links (displays metadata about the target, instead of the symbolic link itself, while still showing the name of the symbolic link).

-o

Omit color in the output.

-p

Equivalent to -F.

-F

Mark file type by adding a suffix (nothing for plain file, * for executable, / for directory, @ for symbolic link).

-r

Reverse sort order.

-R

List recursively.

-S

Sort by size.

-t

Sort by modification time.

-X

Sort by extension.

Documentation

For more information on ls, consult its man page, which you can view online or by running the man 1 ls command on your GNU/Linux system.