sys/contrib/openzfs/man/man8/zfs-list.8

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