docs: improve wording and formatting of blkid man page
Furthermore, explain the device argument right at the beginning, since it is not an option, and alphabetize -k. Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
This commit is contained in:
Benno Schulenberg
Karel Zak
parent
36c7f78524
commit
bc88ad1a5f
|
|
@ -5,15 +5,14 @@
|
|||
.\" 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" "util-linux" "System Administration"
|
||||
.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
|
||||
.BI \-L " label"
|
||||
|
|
||||
.BI \-U " uuid"
|
||||
|
||||
.B blkid
|
||||
.RB [ \-dghlv ]
|
||||
|
|
@ -21,22 +20,21 @@ blkid \- locate/print block device attributes
|
|||
.IR file ]
|
||||
.RB [ \-o
|
||||
.IR format ]
|
||||
.in +6
|
||||
.RB [ \-s
|
||||
.IR tag ]
|
||||
.in +6
|
||||
.RB [ \-t
|
||||
.IR NAME=value ]
|
||||
[\fIdevice\fR ...]
|
||||
.RI [ device " ...]"
|
||||
.in -6
|
||||
|
||||
.B blkid
|
||||
.RB -p
|
||||
.RB [ \-O
|
||||
.BR -p " [" \-O
|
||||
.IR offset ]
|
||||
.RB [ \-S
|
||||
.IR size ]
|
||||
.RB [ \-o
|
||||
.IR format ]
|
||||
.RB [ \-S
|
||||
.IR size ]
|
||||
.RB [ \-s
|
||||
.IR tag ]
|
||||
.in +9
|
||||
|
|
@ -44,16 +42,15 @@ blkid \- locate/print block device attributes
|
|||
.IR list ]
|
||||
.RB [ \-u
|
||||
.IR list ]
|
||||
.IR device " ... "
|
||||
.IR device " ..."
|
||||
.in -9
|
||||
|
||||
.B blkid
|
||||
.RB -i
|
||||
.RB [ \-o
|
||||
.BR -i " [" \-o
|
||||
.IR format ]
|
||||
.RB [ \-s
|
||||
.IR tag ]
|
||||
.IR device " ... "
|
||||
.IR device " ..."
|
||||
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
|
|
@ -61,15 +58,25 @@ 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
|
||||
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
|
||||
Note that
|
||||
.B blkid
|
||||
reads information directly from devices and for non-root users
|
||||
it returns cached unverified information. It's better to use
|
||||
it returns cached unverified information. It is better to use
|
||||
.B lsblk --fs
|
||||
to get user-friendly overview about filesystems and devices.
|
||||
to get a user-friendly overview of filesystems and devices.
|
||||
.BR lsblk (8)
|
||||
is also easy to use in scripts.
|
||||
.B blkid
|
||||
|
|
@ -81,22 +88,22 @@ specific NAME=value pair, or displaying NAME=value pairs for one or
|
|||
more specified devices.
|
||||
.SH OPTIONS
|
||||
The \fIsize\fR and \fIoffset\fR arguments may be followed by the multiplicative
|
||||
suffixes 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.
|
||||
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"
|
||||
Read from
|
||||
.I cachefile
|
||||
instead of reading from the default cache file (see CONFIGURATION FILE section
|
||||
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 different encoding and this encoding cannot be disabled.
|
||||
Don't encode non-printing characters. The non-printing characters are encoded
|
||||
by ^ and M- notation by default. Note that the \fB-o udev\fR output format uses
|
||||
a different encoding which cannot be disabled.
|
||||
.TP
|
||||
.B \-g
|
||||
Perform a garbage collection pass on the blkid cache to remove
|
||||
|
|
@ -106,36 +113,37 @@ devices which no longer exist.
|
|||
Display a usage message and exit.
|
||||
.TP
|
||||
.B \-i
|
||||
Display I/O Limits (aka I/O topology) information. The 'export' output format is
|
||||
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-p\fR option.
|
||||
.TP
|
||||
.B \-l
|
||||
Look up only one device that matches the search parameter specified with \fB-t\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
|
||||
.B \-k
|
||||
List all known filesystems and RAIDs and exit.
|
||||
.TP
|
||||
.B \-l
|
||||
Look up only one device that matches the search parameter specified with the \fB-t\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
|
||||
.BI \-L " label"
|
||||
Look up the device that uses this filesystem \fIlabel\fR (equal to: -l -o device -t
|
||||
LABEL=<label>). This lookup method is able to reliably use /dev/disk/by-label
|
||||
Look up the device that uses this filesystem \fIlabel\fR; this is equal to
|
||||
.BR "-l -o device -t 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.
|
||||
|
||||
Unfortunately, the original
|
||||
.BR 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.
|
||||
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 "
|
||||
.BI \-n " list"
|
||||
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.
|
||||
|
|
@ -151,10 +159,8 @@ probes for all supported formats except minix filesystems.
|
|||
This option is only useful together with \fB-p\fR.
|
||||
.TP
|
||||
.BI \-o " format"
|
||||
Display
|
||||
.BR blkid 's
|
||||
output using the specified format. Note that the variables order and
|
||||
devices order is variable. See also \fB-s\fR. The
|
||||
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
|
||||
|
|
@ -167,13 +173,14 @@ 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-p\fR or \fB-i\fR). This output format is \fBDEPRECATED\fR
|
||||
in favour of
|
||||
for low-level probing (\fB-p\fR or \fB-i\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
|
||||
print the device name only; this output format is always enabled for the \fB-L\fR
|
||||
and \fB-U\fR options
|
||||
.TP
|
||||
.B udev
|
||||
|
|
@ -182,7 +189,7 @@ 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.
|
||||
partitions. This output format is \fBDEPRECATED\fR.
|
||||
.TP
|
||||
.B export
|
||||
print key=value pairs for easy import into the environment; this output format
|
||||
|
|
@ -194,7 +201,7 @@ Probe at the given \fIoffset\fR (only useful with \fB-p\fR). This option can be
|
|||
used together with the \fB-i\fR option.
|
||||
.TP
|
||||
.BI \-p
|
||||
Switch to low-level superblock probing mode (bypass cache).
|
||||
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).
|
||||
|
|
@ -211,9 +218,9 @@ In order to just refresh the cache without showing any tokens, use
|
|||
with no other options.
|
||||
.TP
|
||||
.BI \-S " size"
|
||||
Overwrite device/file size (only useful with \fB-p\fR).
|
||||
Override the size of device/file (only useful with \fB-p\fR).
|
||||
.TP
|
||||
.BI \-t " NAME" = "value"
|
||||
.BI \-t " NAME" = value
|
||||
Search for block devices with tokens named
|
||||
.I NAME
|
||||
that have the value
|
||||
|
|
@ -229,7 +236,7 @@ and
|
|||
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 "
|
||||
.BI \-u " list"
|
||||
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:
|
||||
|
|
@ -243,20 +250,11 @@ probes for all filesystem and other (e.g. swap) formats, and
|
|||
probes for all supported formats except RAIDs.
|
||||
This option is only useful together with \fB-p\fR.
|
||||
.TP
|
||||
.BI \-U " uuid "
|
||||
.BI \-U " uuid"
|
||||
Look up the device that uses this filesystem \fIuuid\fR. For more details see the \fB-L\fR option.
|
||||
.TP
|
||||
.B \-v
|
||||
Display version number and exit.
|
||||
.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.
|
||||
|
|
@ -266,7 +264,7 @@ 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 low-level probing result was detected, an exit code of 8 is
|
||||
returned.
|
||||
.SH CONFIGURATION FILE
|
||||
The standard location of the
|
||||
|
|
@ -277,20 +275,20 @@ The following options control the libblkid library:
|
|||
.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".
|
||||
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
|
||||
.I /run/blkid/blkid.tab
|
||||
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 /run directory
|
||||
on systems without a /run directory.
|
||||
.TP
|
||||
.I EVALUATE=<methods>
|
||||
Defines LABEL and UUID evaluation method(s). Currently, the libblkid library
|
||||
supports "udev" and "scan" methods. More than one methods may be specified in
|
||||
a comma separated list. Default is "udev,scan". The "udev" method uses udev
|
||||
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
|
||||
|
|
@ -300,8 +298,7 @@ file.
|
|||
was written by Andreas Dilger for libblkid and improved by Theodore Ts'o
|
||||
and Karel Zak.
|
||||
.SH ENVIRONMENT
|
||||
.IP LIBBLKID_DEBUG=0xffff
|
||||
enables debug output.
|
||||
.IP "Setting LIBBLKID_DEBUG=0xffff enables debug output."
|
||||
.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/.
|
||||
|
|
|
|||
Loading…
Reference in New Issue