.\" Copyright 2000 Andreas Dilger (adilger@turbolinux.com)
.\"
-.\" This man page was created for blkid from e2fsprogs-1.25.
-.\"
.\" This file may be copied under the terms of the GNU Public License.
-.\"
-.\" Based on uuidgen, Mon Sep 17 10:42:12 2000, Andreas Dilger
-.TH BLKID 8 "February 2011" "Linux" "MAINTENANCE COMMANDS"
+.TH BLKID 8 "March 2013" "util-linux" "System Administration"
.SH NAME
blkid \- locate/print block device attributes
.SH SYNOPSIS
-.B blkid
-.RB \-L
-.IR label " | "
-.RB \-U
-.IR uuid
+.IP \fBblkid\fR
+.BI \-\-label " label"
+|
+.BI \-\-uuid " uuid"
-.B blkid
-.RB [ \-dghlv ]
-.RB [ \-c
-.IR file ]
-.RB [ \-w
+.IP \fBblkid\fR
+.RB [ \-\-no\-encoding
+.B \-\-garbage\-collect \-\-list\-one \-\-cache\-file
.IR file ]
-.RB [ \-o
+.RB [ \-\-output
.IR format ]
-.in +6
-.RB [ \-s
+.RB [ \-\-match\-tag
.IR tag ]
-.RB [ \-t
+.RB [ \-\-match\-token
.IR NAME=value ]
-[\fIdevice\fR ...]
-.in -6
+.RI [ device " ...]"
-.B blkid
-.RB -p
-.RB [ \-O
+.IP \fBblkid\fR
+.BR \-\-probe " [" \-\-offset
.IR offset ]
-.RB [ \-S
-.IR size ]
-.RB [ \-o
+.RB [ \-\-output
.IR format ]
-.RB [ \-s
+.RB [ \-\-size
+.IR size ]
+.RB [ \-\-match\-tag
.IR tag ]
-.in +9
-.RB [ \-n
+.RB [ \-\-match\-types
.IR list ]
-.RB [ \-u
+.RB [ \-\-usages
.IR list ]
-.IR device " ... "
-.in -9
+.RB [ \-\-no\-part\-details ]
+.IR device " ..."
-.B blkid
-.RB -i
-.RB [ \-o
+.IP \fBblkid\fR
+.BR \-\-info " [" \-\-output
.IR format ]
-.RB [ \-s
+.RB [ \-\-match\-tag
.IR tag ]
-.IR device " ... "
+.IR device " ..."
.SH DESCRIPTION
The
program is the command-line interface to working with the
.BR libblkid (3)
library. It can determine the type of content (e.g. filesystem or swap)
-that a block device holds, and also attributes (tokens, NAME=value pairs)
+that a block device holds, and also the attributes (tokens, NAME=value pairs)
from the content metadata (e.g. LABEL or UUID fields).
.PP
+.B It is recommended to use
+.BR lsblk (8)
+.B command to get information about block devices, or lsblk --fs to get an overview of filesystems, or
+.BR findmnt (8)
+.B to search in already mounted filesystems.
+.PP
+.RS
+.BR lsblk (8)
+provides more information, better control on output formatting, easy to use in
+scripts and it does not require root permissions to get actual information.
+.B blkid
+reads information directly from devices and for non-root users
+it returns cached unverified information.
+.B blkid
+is mostly designed for system services and to test libblkid functionality.
+.RE
+
+.PP
+When
+.I device
+is specified, tokens from only this device are displayed.
+It is possible to specify multiple
+.I device
+arguments on the command line.
+If none is given, all devices which appear in
+.I /proc/partitions
+are shown, if they are recognized.
+.PP
.B blkid
has two main forms of operation: either searching for a device with a
specific NAME=value pair, or displaying NAME=value pairs for one or
more specified devices.
+
+For security reasons
+.B blkid
+silently ignores all devices where the probing result is ambivalent (multiple
+colliding filesystems are detected). The low-level probing mode (\fB-p\fR)
+provides more information and extra return code in this case.
+It's recommended to use
+.BR wipefs (8)
+to get a detailed overview and to erase obsolete stuff (magic strings) from the device.
+
.SH OPTIONS
-The \fIsize\fR and \fIoffset\fR arguments may be followed by binary (2^N)
-suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the
-same meaning as "KiB") or decimal (10^N) suffixes KB, MB, GB, PB and EB.
+The \fIsize\fR and \fIoffset\fR arguments may be followed by the multiplicative
+suffixes like KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB
+(the "iB" is optional, e.g. "K" has the same meaning as "KiB"), or the suffixes
+KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
.TP
-.BI \-c " cachefile"
+\fB\-c\fR, \fB\-\-cache\-file\fR \fIcachefile\fR
Read from
.I cachefile
-instead of reading from the default cache file
-.IR /etc/blkid.tab .
-If you want to start with a clean cache (i.e. don't report devices previously
-scanned but not necessarily available at this time), specify
+instead of reading from the default cache file (see the CONFIGURATION FILE section
+for more details). If you want to start with a clean cache (i.e. don't report
+devices previously scanned but not necessarily available at this time), specify
.IR /dev/null .
.TP
-.B \-d
-Don't encode non-printing characters. The non-printing characters are encoded
-by ^ and M- notation by default. Note that \fB-o udev\fR output format uses
-a diffrent encoding and this encoding cannot be disabled.
+\fB\-d\fR, \fB\-\-no\-encoding\fR
+Don't encode non-printing characters. The non-printing characters are encoded
+by ^ and M- notation by default. Note that the \fB\-\-output udev\fR output format uses
+a different encoding which cannot be disabled.
+.TP
+\fB\-D\fR, \fB\-\-no\-part\-details\fR
+Don't print information (PART_ENTRY_* tags) from partition table in low-level probing mode.
.TP
-.B \-g
+\fB\-g\fR, \fB\-\-garbage\-collect\fR
Perform a garbage collection pass on the blkid cache to remove
devices which no longer exist.
.TP
-.B \-h
+\fB\-h\fR, \fB\-\-help\fR
Display a usage message and exit.
.TP
-.B \-i
-Display I/O Limits (aka I/O topology) information. The 'export' output format is
-automatically enabled. This option can be used together with the \fB-p\fR option.
+\fB\-i\fR, \fB\-\-info\fR
+Display information about I/O Limits (aka I/O topology). The 'export' output format is
+automatically enabled. This option can be used together with the \fB\-\-probe\fR option.
+.TP
+\fB\-k\fR, \fB\-\-list\-filesystems\fR
+List all known filesystems and RAIDs and exit.
.TP
-.B \-l
-Look up only one device that matches the search parameter specified with the
-.B \-t
+\fB\-l\fR, \fB\-\-list\-one\fR
+Look up only one device that matches the search parameter specified with the \fB\-\-match\-token\fR
option. If there are multiple devices that match the specified search
parameter, then the device with the highest priority is returned, and/or
the first device found at a given priority. Device types in order of
-decreasing priority are Device Mapper, EVMS, LVM, MD, and finally regular
+decreasing priority are: Device Mapper, EVMS, LVM, MD, and finally regular
block devices. If this option is not specified,
.B blkid
will print all of the devices that match the search parameter.
.TP
-.BI \-L " label"
-Look up the device that uses this \fIlabel\fR (equal to: -l -o device -t
-LABEL=<label>). This lookup method is able to reliably use /dev/disk/by-label
+\fB\-L\fR, \fB\-\-label\fR \fIlabel\fR
+Look up the device that uses this filesystem \fIlabel\fR; this is equal to
+.BR "--list-one --output device --match-token LABEL=\fIlabel\fR" .
+This lookup method is able to reliably use /dev/disk/by-label
udev symlinks (dependent on a setting in /etc/blkid.conf). Avoid using the
symlinks directly; it is not reliable to use the symlinks without verification.
-The \fB-L\fR option works on systems with and without udev.
+The \fB-\-label\fR option works on systems with and without udev.
Unfortunately, the original
-.B blkid(8)
-from e2fsprogs use the \fB-L\fR option as a
-synonym for the \fB-o list\fR option. For better portability, use \fB-l -o device
--t LABEL=<label>\fR and \fB-o list\fR in your scripts rather than the \fB-L\fR option.
+.BR blkid (8)
+from e2fsprogs uses the \fB-L\fR option as a
+synonym for \fB-o list\fR. For better portability, use \fB-l -o device
+-t LABEL=\fIlabel\fR and \fB-o list\fR in your scripts rather than the \fB-L\fR option.
.TP
-.BI \-n " list "
+\fB\-n\fR, \fB\-\-match\-types\fR \fIlist\fR
Restrict the probing functions to the specified (comma-separated) \fIlist\fR of
superblock types (names).
The list items may be prefixed with "no" to specify the types which should be ignored.
For example:
.sp
- blkid -p -n vfat,ext3,ext4 /dev/sda1
+ blkid --probe --match-types vfat,ext3,ext4 /dev/sda1
.sp
probes for vfat, ext3 and ext4 filesystems, and
.sp
- blkid -p -n nominix /dev/sda1
+ blkid --probe --match-types nominix /dev/sda1
.sp
probes for all supported formats except minix filesystems.
-This option is only useful together with \fB-p\fR.
+This option is only useful together with \fB\-\-probe\fR.
.TP
-.BI \-o " format"
-Display
-.BR blkid 's
-output using the specified format. The
+\fB\-o\fR, \fB\-\-output\fR \fIformat\fR
+Use the specified output format. Note that the order of variables and
+devices is not fixed. See also option \fB-s\fR. The
.I format
parameter may be:
.RS
.TP
.B list
print the devices in a user-friendly format; this output format is unsupported
-for low-level probing (\fB-p\fR or \fB-i\fR)
+for low-level probing (\fB\-\-probe\fR or \fB\-\-info\fR).
+
+This output format is \fBDEPRECATED\fR in favour of the
+.BR lsblk (8)
+command.
.TP
.B device
-print the device name only; this output format is always enabled for \fB-L\fR
-and \fB-U\fR options
+print the device name only; this output format is always enabled for the \fB\-\-label\fR
+and \fB\-\-uuid\fR options
.TP
.B udev
print key="value" pairs for easy import into the udev environment; the keys are
-prefixed by ID_FS_ or ID_PART_ prefixes
+prefixed by ID_FS_ or ID_PART_ prefixes. The value may be modified to be
+safe for udev environment; allowed is plain ASCII, hex-escaping and valid UTF-8,
+everything else (including whitespaces) is replaced with '_'. The keys with
+_ENC postfix use hex-escaping for unsafe chars.
The udev output returns the ID_FS_AMBIVALENT tag if more superblocks are detected,
and ID_PART_ENTRY_* tags are always returned for all partitions including empty
partitions.
+
+This output format is \fBDEPRECATED\fR.
.TP
.B export
print key=value pairs for easy import into the environment; this output format
-is automatically enabled when I/O Limits (\fB-i\fR option) are requested
+is automatically enabled when I/O Limits (\fB\-\-info\fR option) are requested.
+
+The non-printing characters are encoded by ^ and M- notation and all
+potentially unsafe characters are escaped.
.RE
.TP
-.BI \-O " offset"
-Probe at the given \fIoffset\fR (only useful with \fB-p\fR). This option can be
-used together with the \fB-i\fR option.
+\fB\-O\fR, \fB\-\-offset\fR \fIoffset\fR
+Probe at the given \fIoffset\fR (only useful with \fB\-\-probe\fR). This option can be
+used together with the \fB\-\-info\fR option.
.TP
-.BI \-p
-Switch to low-level superblock probing mode (bypass cache).
+\fB\-p\fR, \fB\-\-probe\fR
+Switch to low-level superblock probing mode (bypassing the cache).
Note that low-level probing also returns information about partition table type
-(PTTYPE tag) and partitions (PART_ENTRY_* tags).
+(PTTYPE tag) and partitions (PART_ENTRY_* tags). The tag names produced by
+low-level probing are based on names used internally by libblkid and it may be
+different than when executed without \fB\-\-probe\fR (for example PART_ENTRY_UUID= vs
+PARTUUID=). See also \fB\-\-no\-part\-details\fR.
.TP
-.BI \-s " tag"
+\fB\-s\fR, \fB\-\-match\-tag\fR \fItag\fR
For each (specified) device, show only the tags that match
.IR tag .
It is possible to specify multiple
-.B \-s
+.B \-\-match\-tag
options. If no tag is specified, then all tokens are shown for all
(specified) devices.
In order to just refresh the cache without showing any tokens, use
-.B "-s none"
+.B "\-\-match\-tag none"
with no other options.
.TP
-.BI \-S " size"
-Overwrite device/file size (only useful with \fB-p\fR).
+\fB\-S\fR, \fB\-\-size\fR \fIsize\fR
+Override the size of device/file (only useful with \fB\-\-probe\fR).
.TP
-.BI \-t " NAME" = "value"
+\fB\-t\fR, \fB\-\-match\-token\fR \fINAME=value\fR
Search for block devices with tokens named
.I NAME
that have the value
If there are no devices specified on the command line, all block devices
will be searched; otherwise only the specified devices are searched.
.TP
-.BI \-u " list "
+\fB\-u\fR, \fB\-\-usages\fR \fIlist\fR
Restrict the probing functions to the specified (comma-separated) \fIlist\fR of "usage" types.
Supported usage types are: filesystem, raid, crypto and other. The list items may be
prefixed with "no" to specify the usage types which should be ignored. For example:
.sp
- blkid -p -u filesystem,other /dev/sda1
+ blkid --probe --usages filesystem,other /dev/sda1
.sp
probes for all filesystem and other (e.g. swap) formats, and
.sp
- blkid -p -u noraid /dev/sda1
+ blkid --probe --usages noraid /dev/sda1
.sp
probes for all supported formats except RAIDs.
-This option is only useful together with \fB-p\fR.
+This option is only useful together with \fB\-\-probe\fR.
.TP
-.BI \-U " uuid "
-Look up the device that uses this \fIuuid\fR. For more details see the \fB-L\fR option.
+\fB\-U\fR, \fB\-\-uuid\fR \fIuuid\fR
+Look up the device that uses this filesystem \fIuuid\fR. For more details see the
+\fB\-\-label\fR option.
.TP
-.B \-v
+\fB\-V\fR, \fB\-\-version\fR
Display version number and exit.
-.TP
-.BI \-w " writecachefile"
-Write the device cache to
-.I writecachefile
-instead of writing it to the default cache file
-.IR /etc/blkid.tab .
-If you don't want to save the cache at all, specify
-.IR /dev/null.
-If not specified, it will be the same file as that given with the
-.B \-c
-option.
-.TP
-.I device
-Display tokens from only the specified device. It is possible to
-give multiple
-.I device
-options on the command line. If none is given, all devices which
-appear in
-.I /proc/partitions
-are shown, if they are recognized.
.SH "RETURN CODE"
-If the specified token was found, or if any tags were shown from (specified)
-devices, 0 is returned.
+If the specified device or device addressed by specified token (option
+\fB\-\-match\-token\fR) was found and it's possible to gather any information about the
+device, an exit code 0 is returned. Note the option \fB\-\-match\-tag\fR filters output
+tags, but it does not affect return code.
If the specified token was not found, or no (specified) devices could be
identified, an exit code of 2 is returned.
For usage or other errors, an exit code of 4 is returned.
-If the ambivalent low-level probing result was detected, an exit code of 8 is
+If an ambivalent probing result was detected by low-level probing mode (\fB\-p\fR), an exit code of 8 is
returned.
+.SH CONFIGURATION FILE
+The standard location of the
+.I /etc/blkid.conf
+config file can be overridden by the environment variable BLKID_CONF.
+The following options control the libblkid library:
+.TP
+.I SEND_UEVENT=<yes|not>
+Sends uevent when
+.I /dev/disk/by-{label,uuid,partuuid,partlabel}/
+symlink does not match with LABEL, UUID, PARTUUID or PARTLABEL on the device. Default is "yes".
+.TP
+.I CACHE_FILE=<path>
+Overrides the standard location of the cache file. This setting can be
+overridden by the environment variable BLKID_FILE. Default is
+.IR /run/blkid/blkid.tab ,
+or
+.I /etc/blkid.tab
+on systems without a /run directory.
+.TP
+.I EVALUATE=<methods>
+Defines LABEL and UUID evaluation method(s). Currently, the libblkid library
+supports the "udev" and "scan" methods. More than one method may be specified in
+a comma-separated list. Default is "udev,scan". The "udev" method uses udev
+.I /dev/disk/by-*
+symlinks and the "scan" method scans all block devices from the
+.I /proc/partitions
+file.
.SH AUTHOR
.B blkid
was written by Andreas Dilger for libblkid and improved by Theodore Ts'o
and Karel Zak.
+.SH ENVIRONMENT
+.IP "Setting LIBBLKID_DEBUG=all enables debug output."
+.SH SEE ALSO
+.BR libblkid (3),
+.BR findfs (8),
+.BR lsblk (8),
+.BR wipefs (8)
.SH AVAILABILITY
The blkid command is part of the util-linux package and is available from
-ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
-.SH "SEE ALSO"
-.BR libblkid (3)
-.BR findfs (8)
-.BR wipefs (8)
+https://www.kernel.org/pub/linux/utils/util-linux/.
projects / thirdparty / util-linux.git / blobdiff