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 52If specified, you can list property information by the absolute pathname or the 53relative pathname. 54By default, all file systems and volumes are displayed. 55Snapshots are displayed if the 56.Sy listsnapshots 57pool property is 58.Sy on 59.Po the default is 60.Sy off 61.Pc , 62or if the 63.Fl t Sy snapshot 64or 65.Fl t Sy all 66options are specified. 67The following fields are displayed: 68.Sy name , Sy used , Sy available , Sy referenced , Sy mountpoint . 69.Bl -tag -width "-H" 70.It Fl H 71Used for scripting mode. 72Do not print headers and separate fields by a single tab instead of arbitrary 73white space. 74.It Fl j , -json Op Ar --json-int 75Print the output in JSON format. 76Specify 77.Sy --json-int 78to print the numbers in integer format instead of strings in JSON output. 79.It Fl d Ar depth 80Recursively display any children of the dataset, limiting the recursion to 81.Ar depth . 82A 83.Ar depth 84of 85.Sy 1 86will display only the dataset and its direct children. 87.It Fl o Ar property 88A comma-separated list of properties to display. 89The property must be: 90.Bl -bullet -compact 91.It 92One of the properties described in the 93.Sx Native Properties 94section of 95.Xr zfsprops 7 96.It 97A user property 98.It 99The value 100.Sy name 101to display the dataset name 102.It 103The value 104.Sy space 105to display space usage properties on file systems and volumes. 106This 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 112Display numbers in parsable 113.Pq exact 114values. 115.It Fl r 116Recursively display any children of the dataset on the command line. 117.It Fl s Ar property 118A property for sorting the output by column in ascending order based on the 119value of the property. 120The property must be one of the properties described in the 121.Sx Properties 122section of 123.Xr zfsprops 7 124or the value 125.Sy name 126to sort by the dataset name. 127Multiple properties can be specified at one time using multiple 128.Fl s 129property options. 130Multiple 131.Fl s 132options are evaluated from left to right in decreasing order of importance. 133The following is a list of sorting criteria: 134.Bl -bullet -compact 135.It 136Numeric types sort in numeric order. 137.It 138String types sort in alphabetical order. 139.It 140Types inappropriate for a row sort that row to the literal bottom, regardless of 141the specified ordering. 142.El 143.Pp 144If no sorting options are specified the existing behavior of 145.Nm zfs Cm list 146is preserved. 147.It Fl S Ar property 148Same as 149.Fl s , 150but sorts by property in descending order. 151.It Fl t Ar type 152A comma-separated list of types to display, where 153.Ar type 154is one of 155.Sy filesystem , 156.Sy snapshot , 157.Sy volume , 158.Sy bookmark , 159or 160.Sy all . 161For example, specifying 162.Fl t Sy snapshot 163displays only snapshots. 164.Sy fs , 165.Sy snap , 166or 167.Sy vol 168can be used as aliases for 169.Sy filesystem , 170.Sy snapshot , 171or 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 179The following command lists all active file systems and volumes in the system. 180Snapshots are displayed if 181.Sy listsnaps Ns = Ns Sy on . 182The default is 183.Sy off . 184See 185.Xr zpoolprops 7 186for more information on pool properties. 187.Bd -literal -compact -offset Ds 188.No # Nm zfs Cm list 189NAME USED AVAIL REFER MOUNTPOINT 190pool 450K 457G 18K /pool 191pool/home 315K 457G 21K /export/home 192pool/home/anne 18K 457G 18K /export/home/anne 193pool/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 354