Adding upstream version 2.36.1.upstream/2.36.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 343 insertions, 0 deletions

diff --git a/misc-utils/blkid.8 b/misc-utils/blkid.8
new file mode 100644
index 0000000..57a3b75
--- /dev/null
+++ b/misc-utils/blkid.8
@@ -0,0 +1,343 @@
+.\" 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 ]
+.RB [ \-\-no\-part\-details ]
+.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 partitions or unpartitioned 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 exit status 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\-D\fR, \fB\-\-no\-part\-details\fR
+Don't print information (PART_ENTRY_* tags) from partition table in low-level probing mode.
+.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 (but see below note about udev).
+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.
+.sp
+This option forces
+.B blkid
+to use udev when used for LABEL or UUID tokens in \fB\-\-match\-token\fR. The
+goal is to provide output consistent with other utils (like mount, etc.)
+on systems where the same tag is used for multiple devices.
+.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 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\-\-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=). See also \fB\-\-no\-part\-details\fR.
+.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 EXIT STATUS
+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 status 0 is returned.  Note the option \fB\-\-match\-tag\fR filters output
+tags, but it does not affect exit status.
+
+If the specified token was not found, or no (specified) devices could be
+identified, or it is impossible to gather any information about the device
+identifiers or device content an exit status of 2 is returned.
+
+For usage or other errors, an exit status of 4 is returned.
+
+If an ambivalent probing result was detected by low-level probing mode (\fB\-p\fR), an exit status 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 ENVIRONMENT
+.IP "Setting LIBBLKID_DEBUG=all enables debug output."
+.SH AUTHORS
+.B blkid
+was written by Andreas Dilger for libblkid and improved by Theodore Ts'o
+and Karel Zak.
+.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/.