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