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