| .\" Copyright 2000 Andreas Dilger (adilger@turbolinux.com) |
| .\" |
| .\" This file may be copied under the terms of the GNU Public License. |
| .TH BLKID 8 "March 2013" "util-linux" "System Administration" |
| .SH NAME |
| blkid \- locate/print block device attributes |
| .SH SYNOPSIS |
| .IP \fBblkid\fR |
| .BI \-\-label " label" |
| | |
| .BI \-\-uuid " uuid" |
| |
| .IP \fBblkid\fR |
| .RB [ \-\-no\-encoding |
| .B \-\-garbage\-collect \-\-list\-one \-\-cache\-file |
| .IR file ] |
| .RB [ \-\-output |
| .IR format ] |
| .RB [ \-\-match\-tag |
| .IR tag ] |
| .RB [ \-\-match\-token |
| .IR NAME=value ] |
| .RI [ device " ...]" |
| |
| .IP \fBblkid\fR |
| .BR \-\-probe " [" \-\-offset |
| .IR offset ] |
| .RB [ \-\-output |
| .IR format ] |
| .RB [ \-\-size |
| .IR size ] |
| .RB [ \-\-match\-tag |
| .IR tag ] |
| .RB [ \-\-match\-types |
| .IR list ] |
| .RB [ \-\-usages |
| .IR list ] |
| .IR device " ..." |
| |
| .IP \fBblkid\fR |
| .BR \-\-info " [" \-\-output |
| .IR format ] |
| .RB [ \-\-match\-tag |
| .IR tag ] |
| .IR device " ..." |
| |
| .SH DESCRIPTION |
| The |
| .B blkid |
| 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 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 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 |
| \fB\-c\fR, \fB\-\-cache\-file\fR \fIcachefile\fR |
| Read from |
| .I cachefile |
| 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 |
| \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\-g\fR, \fB\-\-garbage\-collect\fR |
| Perform a garbage collection pass on the blkid cache to remove |
| devices which no longer exist. |
| .TP |
| \fB\-h\fR, \fB\-\-help\fR |
| Display a usage message and exit. |
| .TP |
| \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 |
| \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 |
| block devices. If this option is not specified, |
| .B blkid |
| will print all of the devices that match the search parameter. |
| .TP |
| \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-\-label\fR option works on systems with and without udev. |
| |
| Unfortunately, the original |
| .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 |
| \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 --probe --match-types vfat,ext3,ext4 /dev/sda1 |
| .sp |
| probes for vfat, ext3 and ext4 filesystems, and |
| .sp |
| blkid --probe --match-types nominix /dev/sda1 |
| .sp |
| probes for all supported formats except minix filesystems. |
| This option is only useful together with \fB\-\-probe\fR. |
| .TP |
| \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 full |
| print all tags (the default) |
| .TP |
| .B value |
| print the value of the tags |
| .TP |
| .B list |
| print the devices in a user-friendly format; this output format is unsupported |
| 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 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 |
| |
| 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\-\-info\fR option) are requested. |
| |
| The non-printing characters are encoded by ^ and M- notation and all |
| potentially unsafe characters are escaped. |
| .RE |
| .TP |
| \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 |
| \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). 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=). |
| .TP |
| \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 \-\-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 "\-\-match\-tag none" |
| with no other options. |
| .TP |
| \fB\-S\fR, \fB\-\-size\fR \fIsize\fR |
| Override the size of device/file (only useful with \fB\-\-probe\fR). |
| .TP |
| \fB\-t\fR, \fB\-\-match\-token\fR \fINAME=value\fR |
| Search for block devices with tokens named |
| .I NAME |
| that have the value |
| .IR value , |
| and display any devices which are found. |
| Common values for |
| .I NAME |
| include |
| .BR TYPE , |
| .BR LABEL , |
| and |
| .BR UUID . |
| If there are no devices specified on the command line, all block devices |
| will be searched; otherwise only the specified devices are searched. |
| .TP |
| \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 --probe --usages filesystem,other /dev/sda1 |
| .sp |
| probes for all filesystem and other (e.g. swap) formats, and |
| .sp |
| blkid --probe --usages noraid /dev/sda1 |
| .sp |
| probes for all supported formats except RAIDs. |
| This option is only useful together with \fB\-\-probe\fR. |
| .TP |
| \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 |
| \fB\-V\fR, \fB\-\-version\fR |
| Display version number and exit. |
| .SH "RETURN CODE" |
| 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 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 |
| https://www.kernel.org/pub/linux/utils/util-linux/. |