Querying ZFS File System Information

The zfs list command provides an extensible mechanism for viewing and querying dataset information. Both basic and complex queries are explained in this section.

Listing Basic ZFS Information

You can list basic dataset information by using the zfs list command with no options. This command displays the names of all datasets on the system and the values of their used, available, referenced, and mountpoint properties. For more information about these properties, see Introducing ZFS Properties.

For example:

# zfs list
NAME                   USED  AVAIL  REFER  MOUNTPOINT
pool                   476K  16.5G    21K  /pool
pool/clone              18K  16.5G    18K  /pool/clone
pool/home              296K  16.5G    19K  /pool/home
pool/home/marks        277K  16.5G   277K  /pool/home/marks
pool/home/marks@snap      0      -   277K  -
pool/test               18K  16.5G    18K  /test

You can also use this command to display specific datasets by providing the dataset name on the command line. Additionally, use the -r option to recursively display all descendents of that dataset. For example:

# zfs list -r pool/home/marks
NAME                   USED  AVAIL  REFER  MOUNTPOINT
pool/home/marks        277K  16.5G   277K  /pool/home/marks
pool/home/marks@snap      0      -   277K  -

You can use the zfs list command with the mount point of a file system. For example:

# zfs list /pool/home/marks
NAME              USED  AVAIL  REFER  MOUNTPOINT
pool/home/marks   277K  16.5G   277K  /pool/home/marks

The following example shows how to display basic information about tank/home/chua and all of its descendent datasets:

# zfs list -r tank/home/chua
NAME                        USED  AVAIL  REFER  MOUNTPOINT 
tank/home/chua                  26.0K  4.81G  10.0K  /tank/home/chua 
tank/home/chua/projects       16K  4.81G   9.0K  /tank/home/chua/projects
tank/home/chua/projects/fs1    8K  4.81G     8K  /tank/home/chua/projects/fs1 
tank/home/chua/projects/fs2    8K  4.81G     8K  /tank/home/chua/projects/fs2

For additional information about the zfs list command, see zfs(1M).

Creating Complex ZFS Queries

The zfs list output can be customized by using the -o, -t, and -H options.

You can customize property value output by using the -o option and a comma-separated list of desired properties. You can supply any dataset property as a valid argument. For a list of all supported dataset properties, see Introducing ZFS Properties. In addition to the properties defined, the -o option list can also contain the literal name to indicate that the output should include the name of the dataset.

The following example uses zfs list to display the dataset name, along with the sharenfs and mountpoint property values.

# zfs list -o name,sharenfs,mountpoint
NAME                   SHARENFS         MOUNTPOINT
tank                   off              /tank
tank/home              on               /tank/home
tank/home/ahrens       on               /tank/home/ahrens
tank/home/bonwick      on               /tank/home/bonwick
tank/home/chua         on               /tank/home/chua
tank/home/eschrock     on               legacy
tank/home/moore        on               /tank/home/moore
tank/home/tabriz       ro               /tank/home/tabriz

You can use the -t option to specify the types of datasets to display. The valid types are described in the following table.

Table 6-2 Types of ZFS Datasets

The -t options takes a comma-separated list of the types of datasets to be displayed. The following example uses the -t and -o options simultaneously to show the name and used property for all file systems:

# zfs list -t filesystem -o name,used
NAME              USED
pool              476K
pool/clone         18K
pool/home         296K
pool/home/marks   277K
pool/test          18K

You can use the -H option to omit the zfs list header from the generated output. With the -H option, all white space is replaced by the Tab character. This option can be useful when you need parseable output, for example, when scripting. The following example shows the output generated from using the zfs list command with the -H option:

# zfs list -H -o name
pool
pool/clone
pool/home
pool/home/marks
pool/home/marks@snap
pool/test