| blob | 0fa7e9cc2613cf1cdbff292d6f03338777de7ef1 |
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 https://opensource.org/licenses/CDDL-1.0.
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 February 8, 2024
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 .Op Fl j Op Ar --json-int
45 .Oo Fl o Ar property Ns Oo , Ns Ar property Oc Ns … Oc
46 .Oo Fl s Ar property Oc Ns …
47 .Oo Fl S Ar property Oc Ns …
48 .Oo Fl t Ar type Ns Oo , Ns Ar type Oc Ns … Oc
49 .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns …
50 .
51 .Sh DESCRIPTION
52 If specified, you can list property information by the absolute pathname or the
53 relative pathname.
54 By default, all file systems and volumes are displayed.
55 Snapshots are displayed if the
56 .Sy listsnapshots
57 pool property is
58 .Sy on
59 .Po the default is
60 .Sy off
61 .Pc ,
62 or if the
63 .Fl t Sy snapshot
64 or
65 .Fl t Sy all
66 options are specified.
67 The following fields are displayed:
68 .Sy name , Sy used , Sy available , Sy referenced , Sy mountpoint .
69 .Bl -tag -width "-H"
70 .It Fl H
71 Used for scripting mode.
72 Do not print headers and separate fields by a single tab instead of arbitrary
73 white space.
74 .It Fl j , -json Op Ar --json-int
75 Print the output in JSON format.
76 Specify
77 .Sy --json-int
78 to print the numbers in integer format instead of strings in JSON output.
79 .It Fl d Ar depth
80 Recursively display any children of the dataset, limiting the recursion to
81 .Ar depth .
82 A
83 .Ar depth
84 of
85 .Sy 1
86 will display only the dataset and its direct children.
87 .It Fl o Ar property
88 A comma-separated list of properties to display.
89 The property must be:
90 .Bl -bullet -compact
91 .It
92 One of the properties described in the
93 .Sx Native Properties
94 section of
95 .Xr zfsprops 7
96 .It
97 A user property
98 .It
99 The value
100 .Sy name
101 to display the dataset name
102 .It
103 The value
104 .Sy space
105 to display space usage properties on file systems and volumes.
106 This is a shortcut for specifying
107 .Fl o Ns \ \& Ns Sy name , Ns Sy avail , Ns Sy used , Ns Sy usedsnap , Ns
108 .Sy usedds , Ns Sy usedrefreserv , Ns Sy usedchild
109 .Fl t Sy filesystem , Ns Sy volume .
110 .El
111 .It Fl p
112 Display numbers in parsable
113 .Pq exact
114 values.
115 .It Fl r
116 Recursively display any children of the dataset on the command line.
117 .It Fl s Ar property
118 A property for sorting the output by column in ascending order based on the
119 value of the property.
120 The property must be one of the properties described in the
121 .Sx Properties
122 section of
123 .Xr zfsprops 7
124 or the value
125 .Sy name
126 to sort by the dataset name.
127 Multiple properties can be specified at one time using multiple
128 .Fl s
129 property options.
130 Multiple
131 .Fl s
132 options are evaluated from left to right in decreasing order of importance.
133 The following is a list of sorting criteria:
134 .Bl -bullet -compact
135 .It
136 Numeric types sort in numeric order.
137 .It
138 String types sort in alphabetical order.
139 .It
140 Types inappropriate for a row sort that row to the literal bottom, regardless of
141 the specified ordering.
142 .El
143 .Pp
144 If no sorting options are specified the existing behavior of
145 .Nm zfs Cm list
146 is preserved.
147 .It Fl S Ar property
148 Same as
149 .Fl s ,
150 but sorts by property in descending order.
151 .It Fl t Ar type
152 A comma-separated list of types to display, where
153 .Ar type
154 is one of
155 .Sy filesystem ,
156 .Sy snapshot ,
157 .Sy volume ,
158 .Sy bookmark ,
159 or
160 .Sy all .
161 For example, specifying
162 .Fl t Sy snapshot
163 displays only snapshots.
164 .Sy fs ,
165 .Sy snap ,
166 or
167 .Sy vol
168 can be used as aliases for
169 .Sy filesystem ,
170 .Sy snapshot ,
171 or
172 .Sy volume .
173 .El
174 .
175 .Sh EXAMPLES
176 .\" These are, respectively, examples 5 from zfs.8
177 .\" Make sure to update them bidirectionally
178 .Ss Example 1 : No Listing ZFS Datasets
179 The following command lists all active file systems and volumes in the system.
180 Snapshots are displayed if
181 .Sy listsnaps Ns = Ns Sy on .
182 The default is
183 .Sy off .
184 See
185 .Xr zpoolprops 7
186 for more information on pool properties.
187 .Bd -literal -compact -offset Ds
188 .No # Nm zfs Cm list
189 NAME USED AVAIL REFER MOUNTPOINT
190 pool 450K 457G 18K /pool
191 pool/home 315K 457G 21K /export/home
192 pool/home/anne 18K 457G 18K /export/home/anne
193 pool/home/bob 276K 457G 276K /export/home/bob
194 .Ed
195 .Ss Example 2 : No Listing ZFS filesystems and snapshots in JSON format
196 .Bd -literal -compact -offset Ds
197 .No # Nm zfs Cm list Fl j Fl t Ar filesystem,snapshot | Cm jq
198 {
199 "output_version": {
200 "command": "zfs list",
201 "vers_major": 0,
202 "vers_minor": 1
203 },
204 "datasets": {
205 "pool": {
206 "name": "pool",
207 "type": "FILESYSTEM",
208 "pool": "pool",
209 "properties": {
210 "used": {
211 "value": "290K",
212 "source": {
213 "type": "NONE",
214 "data": "-"
215 }
216 },
217 "available": {
218 "value": "30.5G",
219 "source": {
220 "type": "NONE",
221 "data": "-"
222 }
223 },
224 "referenced": {
225 "value": "24K",
226 "source": {
227 "type": "NONE",
228 "data": "-"
229 }
230 },
231 "mountpoint": {
232 "value": "/pool",
233 "source": {
234 "type": "DEFAULT",
235 "data": "-"
236 }
237 }
238 }
239 },
240 "pool/home": {
241 "name": "pool/home",
242 "type": "FILESYSTEM",
243 "pool": "pool",
244 "properties": {
245 "used": {
246 "value": "48K",
247 "source": {
248 "type": "NONE",
249 "data": "-"
250 }
251 },
252 "available": {
253 "value": "30.5G",
254 "source": {
255 "type": "NONE",
256 "data": "-"
257 }
258 },
259 "referenced": {
260 "value": "24K",
261 "source": {
262 "type": "NONE",
263 "data": "-"
264 }
265 },
266 "mountpoint": {
267 "value": "/mnt/home",
268 "source": {
269 "type": "LOCAL",
270 "data": "-"
271 }
272 }
273 }
274 },
275 "pool/home/bob": {
276 "name": "pool/home/bob",
277 "type": "FILESYSTEM",
278 "pool": "pool",
279 "properties": {
280 "used": {
281 "value": "24K",
282 "source": {
283 "type": "NONE",
284 "data": "-"
285 }
286 },
287 "available": {
288 "value": "30.5G",
289 "source": {
290 "type": "NONE",
291 "data": "-"
292 }
293 },
294 "referenced": {
295 "value": "24K",
296 "source": {
297 "type": "NONE",
298 "data": "-"
299 }
300 },
301 "mountpoint": {
302 "value": "/mnt/home/bob",
303 "source": {
304 "type": "INHERITED",
305 "data": "pool/home"
306 }
307 }
308 }
309 },
310 "pool/home/bob@v1": {
311 "name": "pool/home/bob@v1",
312 "type": "SNAPSHOT",
313 "pool": "pool",
314 "dataset": "pool/home/bob",
315 "snapshot_name": "v1",
316 "properties": {
317 "used": {
318 "value": "0B",
319 "source": {
320 "type": "NONE",
321 "data": "-"
322 }
323 },
324 "available": {
325 "value": "-",
326 "source": {
327 "type": "NONE",
328 "data": "-"
329 }
330 },
331 "referenced": {
332 "value": "24K",
333 "source": {
334 "type": "NONE",
335 "data": "-"
336 }
337 },
338 "mountpoint": {
339 "value": "-",
340 "source": {
341 "type": "NONE",
342 "data": "-"
343 }
344 }
345 }
346 }
347 }
348 }
349 .Ed
350 .
351 .Sh SEE ALSO
352 .Xr zfsprops 7 ,
353 .Xr zfs-get 8