xref: /freebsd/sys/contrib/openzfs/man/man8/zfs-list.8 (revision 3e8eb5c7f4909209c042403ddee340b2ee7003a5)
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 March 16, 2022
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 d Ar depth
74Recursively display any children of the dataset, limiting the recursion to
75.Ar depth .
76A
77.Ar depth
78of
79.Sy 1
80will display only the dataset and its direct children.
81.It Fl o Ar property
82A comma-separated list of properties to display.
83The property must be:
84.Bl -bullet -compact
85.It
86One of the properties described in the
87.Sx Native Properties
88section of
89.Xr zfsprops 7
90.It
91A user property
92.It
93The value
94.Sy name
95to display the dataset name
96.It
97The value
98.Sy space
99to display space usage properties on file systems and volumes.
100This is a shortcut for specifying
101.Fl o Ns \ \& Ns Sy name , Ns Sy avail , Ns Sy used , Ns Sy usedsnap , Ns
102.Sy usedds , Ns Sy usedrefreserv , Ns Sy usedchild
103.Fl t Sy filesystem , Ns Sy volume .
104.El
105.It Fl p
106Display numbers in parsable
107.Pq exact
108values.
109.It Fl r
110Recursively display any children of the dataset on the command line.
111.It Fl s Ar property
112A property for sorting the output by column in ascending order based on the
113value of the property.
114The property must be one of the properties described in the
115.Sx Properties
116section of
117.Xr zfsprops 7
118or the value
119.Sy name
120to sort by the dataset name.
121Multiple properties can be specified at one time using multiple
122.Fl s
123property options.
124Multiple
125.Fl s
126options are evaluated from left to right in decreasing order of importance.
127The following is a list of sorting criteria:
128.Bl -bullet -compact
129.It
130Numeric types sort in numeric order.
131.It
132String types sort in alphabetical order.
133.It
134Types inappropriate for a row sort that row to the literal bottom, regardless of
135the specified ordering.
136.El
137.Pp
138If no sorting options are specified the existing behavior of
139.Nm zfs Cm list
140is preserved.
141.It Fl S Ar property
142Same as
143.Fl s ,
144but sorts by property in descending order.
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 EXAMPLES
161.\" These are, respectively, examples 5 from zfs.8
162.\" Make sure to update them bidirectionally
163.Ss Example 1 : No Listing ZFS Datasets
164The following command lists all active file systems and volumes in the system.
165Snapshots are displayed if
166.Sy listsnaps Ns = Ns Sy on .
167The default is
168.Sy off .
169See
170.Xr zpoolprops 7
171for more information on pool properties.
172.Bd -literal -compact -offset Ds
173.No # Nm zfs Cm list
174NAME                      USED  AVAIL  REFER  MOUNTPOINT
175pool                      450K   457G    18K  /pool
176pool/home                 315K   457G    21K  /export/home
177pool/home/anne             18K   457G    18K  /export/home/anne
178pool/home/bob             276K   457G   276K  /export/home/bob
179.Ed
180.
181.Sh SEE ALSO
182.Xr zfsprops 7 ,
183.Xr zfs-get 8
184