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