misc-utils/blkid.8

   1 .\" Copyright 2000 Andreas Dilger (adilger@turbolinux.com)
   2 .\"
   3 .\" This man page was created for blkid from e2fsprogs-1.25.
   4 .\"
   5 .\" This file may be copied under the terms of the GNU Public License.
   6 .\"
   7 .\" Based on uuidgen, Mon Sep 17 10:42:12 2000, Andreas Dilger
   8 .TH BLKID 8 "March 2013" "util-linux" "System Administration"
   9 .SH NAME
  10 blkid \- locate/print block device attributes
  11 .SH SYNOPSIS
  12 .B blkid
  13 .BI \-L " label"
  14 |
  15 .BI \-U " uuid"
  16
  17 .B blkid
  18 .RB [ \-dghlv ]
  19 .RB [ \-c
  20 .IR file ]
  21 .RB [ \-o
  22 .IR format ]
  23 .RB [ \-s
  24 .IR tag ]
  25 .in +6
  26 .RB [ \-t
  27 .IR NAME=value ]
  28 .RI [ device " ...]"
  29 .in -6
  30
  31 .B blkid
  32 .BR -p " [" \-O
  33 .IR offset ]
  34 .RB [ \-o
  35 .IR format ]
  36 .RB [ \-S
  37 .IR size ]
  38 .RB [ \-s
  39 .IR tag ]
  40 .in +9
  41 .RB [ \-n
  42 .IR list ]
  43 .RB [ \-u
  44 .IR list ]
  45 .IR device " ..."
  46 .in -9
  47
  48 .B blkid
  49 .BR -i " [" \-o
  50 .IR format ]
  51 .RB [ \-s
  52 .IR tag ]
  53 .IR device " ..."
  54
  55 .SH DESCRIPTION
  56 The
  57 .B blkid
  58 program is the command-line interface to working with the
  59 .BR libblkid (3)
  60 library.  It can determine the type of content (e.g. filesystem or swap)
  61 that a block device holds, and also the attributes (tokens, NAME=value pairs)
  62 from the content metadata (e.g. LABEL or UUID fields).
  63 .PP
  64 When
  65 .I device
  66 is specified, tokens from only this device are displayed.
  67 It is possible to specify multiple
  68 .I device
  69 arguments on the command line.
  70 If none is given, all devices which appear in
  71 .I /proc/partitions
  72 are shown, if they are recognized.
  73 .PP
  74 Note that
  75 .B blkid
  76 reads information directly from devices and for non-root users
  77 it returns cached unverified information.  It is better to use
  78 .B lsblk --fs
  79 to get a user-friendly overview of filesystems and devices.
  80 .BR lsblk (8)
  81 is also easy to use in scripts.
  82 .B blkid
  83 is mostly designed for system services and to test libblkid functionality.
  84 .PP
  85 .B blkid
  86 has two main forms of operation: either searching for a device with a
  87 specific NAME=value pair, or displaying NAME=value pairs for one or
  88 more specified devices.
  89 .SH OPTIONS
  90 The \fIsize\fR and \fIoffset\fR arguments may be followed by the multiplicative
  91 suffixes like KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB
  92 (the "iB" is optional, e.g. "K" has the same meaning as "KiB"), or the suffixes
  93 KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
  94 .TP
  95 .BI \-c " cachefile"
  96 Read from
  97 .I cachefile
  98 instead of reading from the default cache file (see the CONFIGURATION FILE section
  99 for more details).  If you want to start with a clean cache (i.e. don't report
 100 devices previously scanned but not necessarily available at this time), specify
 101 .IR /dev/null .
 102 .TP
 103 .B \-d
 104 Don't encode non-printing characters.  The non-printing characters are encoded
 105 by ^ and M- notation by default.  Note that the \fB-o udev\fR output format uses
 106 a different encoding which cannot be disabled.
 107 .TP
 108 .B \-g
 109 Perform a garbage collection pass on the blkid cache to remove
 110 devices which no longer exist.
 111 .TP
 112 .B \-h
 113 Display a usage message and exit.
 114 .TP
 115 .B \-i
 116 Display information about I/O Limits (aka I/O topology).  The 'export' output format is
 117 automatically enabled.  This option can be used together with the \fB-p\fR option.
 118 .TP
 119 .B \-k
 120 List all known filesystems and RAIDs and exit.
 121 .TP
 122 .B \-l
 123 Look up only one device that matches the search parameter specified with the \fB-t\fR
 124 option.  If there are multiple devices that match the specified search
 125 parameter, then the device with the highest priority is returned, and/or
 126 the first device found at a given priority.  Device types in order of
 127 decreasing priority are: Device Mapper, EVMS, LVM, MD, and finally regular
 128 block devices.  If this option is not specified,
 129 .B blkid
 130 will print all of the devices that match the search parameter.
 131 .TP
 132 .BI \-L " label"
 133 Look up the device that uses this filesystem \fIlabel\fR; this is equal to
 134 .BR "-l -o device -t LABEL=\fIlabel\fR" .
 135 This lookup method is able to reliably use /dev/disk/by-label
 136 udev symlinks (dependent on a setting in /etc/blkid.conf).  Avoid using the
 137 symlinks directly; it is not reliable to use the symlinks without verification.
 138 The \fB-L\fR option works on systems with and without udev.
 139
 140 Unfortunately, the original
 141 .BR blkid (8)
 142 from e2fsprogs uses the \fB-L\fR option as a
 143 synonym for \fB-o list\fR.  For better portability, use \fB-l -o device
 144 -t LABEL=\fIlabel\fR and \fB-o list\fR in your scripts rather than the \fB-L\fR option.
 145 .TP
 146 .BI \-n " list"
 147 Restrict the probing functions to the specified (comma-separated) \fIlist\fR of
 148 superblock types (names).
 149 The list items may be prefixed with "no" to specify the types which should be ignored.
 150 For example:
 151 .sp
 152   blkid -p -n vfat,ext3,ext4 /dev/sda1
 153 .sp
 154 probes for vfat, ext3 and ext4 filesystems, and
 155 .sp
 156   blkid -p -n nominix /dev/sda1
 157 .sp
 158 probes for all supported formats except minix filesystems.
 159 This option is only useful together with \fB-p\fR.
 160 .TP
 161 .BI \-o " format"
 162 Use the specified output format.  Note that the order of variables and
 163 devices is not fixed.  See also option \fB-s\fR.  The
 164 .I format
 165 parameter may be:
 166 .RS
 167 .TP
 168 .B full
 169 print all tags (the default)
 170 .TP
 171 .B value
 172 print the value of the tags
 173 .TP
 174 .B list
 175 print the devices in a user-friendly format; this output format is unsupported
 176 for low-level probing (\fB-p\fR or \fB-i\fR).
 177
 178 This output format is \fBDEPRECATED\fR in favour of the
 179 .BR lsblk (8)
 180 command.
 181 .TP
 182 .B device
 183 print the device name only; this output format is always enabled for the \fB-L\fR
 184 and \fB-U\fR options
 185 .TP
 186 .B udev
 187 print key="value" pairs for easy import into the udev environment; the keys are
 188 prefixed by ID_FS_ or ID_PART_ prefixes
 189
 190 The udev output returns the ID_FS_AMBIVALENT tag if more superblocks are detected,
 191 and ID_PART_ENTRY_* tags are always returned for all partitions including empty
 192 partitions.  This output format is \fBDEPRECATED\fR.
 193 .TP
 194 .B export
 195 print key=value pairs for easy import into the environment; this output format
 196 is automatically enabled when I/O Limits (\fB-i\fR option) are requested
 197 .RE
 198 .TP
 199 .BI \-O " offset"
 200 Probe at the given \fIoffset\fR (only useful with \fB-p\fR).  This option can be
 201 used together with the \fB-i\fR option.
 202 .TP
 203 .BI \-p
 204 Switch to low-level superblock probing mode (bypassing the cache).
 205
 206 Note that low-level probing also returns information about partition table type
 207 (PTTYPE tag) and partitions (PART_ENTRY_* tags).
 208 .TP
 209 .BI \-s " tag"
 210 For each (specified) device, show only the tags that match
 211 .IR tag .
 212 It is possible to specify multiple
 213 .B \-s
 214 options.  If no tag is specified, then all tokens are shown for all
 215 (specified) devices.
 216 In order to just refresh the cache without showing any tokens, use
 217 .B "-s none"
 218 with no other options.
 219 .TP
 220 .BI \-S " size"
 221 Override the size of device/file (only useful with \fB-p\fR).
 222 .TP
 223 .BI \-t " NAME" = value
 224 Search for block devices with tokens named
 225 .I NAME
 226 that have the value
 227 .IR value ,
 228 and display any devices which are found.
 229 Common values for
 230 .I NAME
 231 include
 232 .BR TYPE ,
 233 .BR LABEL ,
 234 and
 235 .BR UUID .
 236 If there are no devices specified on the command line, all block devices
 237 will be searched; otherwise only the specified devices are searched.
 238 .TP
 239 .BI \-u " list"
 240 Restrict the probing functions to the specified (comma-separated) \fIlist\fR of "usage" types.
 241 Supported usage types are: filesystem, raid, crypto and other.  The list items may be
 242 prefixed with "no" to specify the usage types which should be ignored.  For example:
 243 .sp
 244   blkid -p -u filesystem,other /dev/sda1
 245 .sp
 246 probes for all filesystem and other (e.g. swap) formats, and
 247 .sp
 248   blkid -p -u noraid /dev/sda1
 249 .sp
 250 probes for all supported formats except RAIDs.
 251 This option is only useful together with \fB-p\fR.
 252 .TP
 253 .BI \-U " uuid"
 254 Look up the device that uses this filesystem \fIuuid\fR.  For more details see the \fB-L\fR option.
 255 .TP
 256 .B \-V
 257 Display version number and exit.
 258 .SH "RETURN CODE"
 259 If the specified token was found, or if any tags were shown from (specified)
 260 devices, 0 is returned.
 261
 262 If the specified token was not found, or no (specified) devices could be
 263 identified, an exit code of 2 is returned.
 264
 265 For usage or other errors, an exit code of 4 is returned.
 266
 267 If an ambivalent low-level probing result was detected, an exit code of 8 is
 268 returned.
 269 .SH CONFIGURATION FILE
 270 The standard location of the
 271 .I /etc/blkid.conf
 272 config file can be overridden by the environment variable BLKID_CONF.
 273 The following options control the libblkid library:
 274 .TP
 275 .I SEND_UEVENT=<yes|not>
 276 Sends uevent when
 277 .I /dev/disk/by-{label,uuid,partuuid,partlabel}/
 278 symlink does not match with LABEL, UUID, PARTUUID or PARTLABEL on the device.  Default is "yes".
 279 .TP
 280 .I CACHE_FILE=<path>
 281 Overrides the standard location of the cache file.  This setting can be
 282 overridden by the environment variable BLKID_FILE.  Default is
 283 .IR /run/blkid/blkid.tab ,
 284 or
 285 .I /etc/blkid.tab
 286 on systems without a /run directory.
 287 .TP
 288 .I EVALUATE=<methods>
 289 Defines LABEL and UUID evaluation method(s).  Currently, the libblkid library
 290 supports the "udev" and "scan" methods.  More than one method may be specified in
 291 a comma-separated list.  Default is "udev,scan".  The "udev" method uses udev
 292 .I /dev/disk/by-*
 293 symlinks and the "scan" method scans all block devices from the
 294 .I /proc/partitions
 295 file.
 296 .SH AUTHOR
 297 .B blkid
 298 was written by Andreas Dilger for libblkid and improved by Theodore Ts'o
 299 and Karel Zak.
 300 .SH ENVIRONMENT
 301 .IP "Setting LIBBLKID_DEBUG=0xffff enables debug output."
 302 .SH AVAILABILITY
 303 The blkid command is part of the util-linux package and is available from
 304 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
 305 .SH "SEE ALSO"
 306 .BR libblkid (3)
 307 .BR findfs (8)
 308 .BR wipefs (8)