misc-utils/blkid.8

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