xref: /freebsd/sys/contrib/openzfs/man/man8/zfs-list.8 (revision dc318a4ffabcbfa23bb56a33403aad36e6de30af)
1.\"
2.\" CDDL HEADER START
3.\"
4.\" The contents of this file are subject to the terms of the
5.\" Common Development and Distribution License (the "License").
6.\" You may not use this file except in compliance with the License.
7.\"
8.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9.\" or http://www.opensolaris.org/os/licensing.
10.\" See the License for the specific language governing permissions
11.\" and limitations under the License.
12.\"
13.\" When distributing Covered Code, include this CDDL HEADER in each
14.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15.\" If applicable, add the following below this CDDL HEADER, with the
16.\" fields enclosed by brackets "[]" replaced with your own identifying
17.\" information: Portions Copyright [yyyy] [name of copyright owner]
18.\"
19.\" CDDL HEADER END
20.\"
21.\" Copyright (c) 2009 Sun Microsystems, Inc. All Rights Reserved.
22.\" Copyright 2011 Joshua M. Clulow <josh@sysmgr.org>
23.\" Copyright (c) 2011, 2019 by Delphix. All rights reserved.
24.\" Copyright (c) 2013 by Saso Kiselkov. All rights reserved.
25.\" Copyright (c) 2014, Joyent, Inc. All rights reserved.
26.\" Copyright (c) 2014 by Adam Stevko. All rights reserved.
27.\" Copyright (c) 2014 Integros [integros.com]
28.\" Copyright 2019 Richard Laager. All rights reserved.
29.\" Copyright 2018 Nexenta Systems, Inc.
30.\" Copyright 2019 Joyent, Inc.
31.\"
32.Dd May 27, 2021
33.Dt ZFS-LIST 8
34.Os
35.
36.Sh NAME
37.Nm zfs-list
38.Nd list properties of ZFS datasets
39.Sh SYNOPSIS
40.Nm zfs
41.Cm list
42.Op Fl r Ns | Ns Fl d Ar depth
43.Op Fl Hp
44.Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns … Oc
45.Oo Fl s Ar property Oc Ns …
46.Oo Fl S Ar property Oc Ns …
47.Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc
48.Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns …
49.
50.Sh DESCRIPTION
51If specified, you can list property information by the absolute pathname or the
52relative pathname.
53By default, all file systems and volumes are displayed.
54Snapshots are displayed if the
55.Sy listsnapshots
56pool property is
57.Sy on
58.Po the default is
59.Sy off
60.Pc ,
61or if the
62.Fl t Sy snapshot
63or
64.Fl t Sy all
65options are specified.
66The following fields are displayed:
67.Sy name , Sy used , Sy available , Sy referenced , Sy mountpoint .
68.Bl -tag -width "-H"
69.It Fl H
70Used for scripting mode.
71Do not print headers and separate fields by a single tab instead of arbitrary
72white space.
73.It Fl S Ar property
74Same as the
75.Fl s
76option, but sorts by property in descending order.
77.It Fl d Ar depth
78Recursively display any children of the dataset, limiting the recursion to
79.Ar depth .
80A
81.Ar depth
82of
83.Sy 1
84will display only the dataset and its direct children.
85.It Fl o Ar property
86A comma-separated list of properties to display.
87The property must be:
88.Bl -bullet -compact
89.It
90One of the properties described in the
91.Sx Native Properties
92section of
93.Xr zfsprops 8
94.It
95A user property
96.It
97The value
98.Sy name
99to display the dataset name
100.It
101The value
102.Sy space
103to display space usage properties on file systems and volumes.
104This is a shortcut for specifying
105.Fl o Ns \ \& Ns Sy name , Ns Sy avail , Ns Sy used , Ns Sy usedsnap , Ns
106.Sy usedds , Ns Sy usedrefreserv , Ns Sy usedchild
107.Fl t Sy filesystem , Ns Sy volume .
108.El
109.It Fl p
110Display numbers in parsable
111.Pq exact
112values.
113.It Fl r
114Recursively display any children of the dataset on the command line.
115.It Fl s Ar property
116A property for sorting the output by column in ascending order based on the
117value of the property.
118The property must be one of the properties described in the
119.Sx Properties
120section of
121.Xr zfsprops 8
122or the value
123.Sy name
124to sort by the dataset name.
125Multiple properties can be specified at one time using multiple
126.Fl s
127property options.
128Multiple
129.Fl s
130options are evaluated from left to right in decreasing order of importance.
131The following is a list of sorting criteria:
132.Bl -bullet -compact
133.It
134Numeric types sort in numeric order.
135.It
136String types sort in alphabetical order.
137.It
138Types inappropriate for a row sort that row to the literal bottom, regardless of
139the specified ordering.
140.El
141.Pp
142If no sorting options are specified the existing behavior of
143.Nm zfs Cm list
144is preserved.
145.It Fl t Ar type
146A comma-separated list of types to display, where
147.Ar type
148is one of
149.Sy filesystem ,
150.Sy snapshot ,
151.Sy volume ,
152.Sy bookmark ,
153or
154.Sy all .
155For example, specifying
156.Fl t Sy snapshot
157displays only snapshots.
158.El
159.
160.Sh SEE ALSO
161.Xr zfs-get 8 ,
162.Xr zfsprops 8
163