[thirdparty/util-linux.git] / misc-utils / lsblk.8

.TH LSBLK 8 "February 2013" "util-linux" "System Administration"
.SH NAME
lsblk \- list block devices
.SH SYNOPSIS
.B lsblk
[options]
.RI [ device ...]
.SH DESCRIPTION
.B lsblk
lists information about all available or the specified block devices.  The
.B lsblk
command reads the
.B sysfs
filesystem and
.B udev db
to gather information. If the udev db is not available or lsblk is compiled without udev support than it
tries to read LABELs, UUIDs and filesystem types from the block device. In this case root permissions
are necessary.
.PP
The command prints all block devices (except RAM disks) in a tree-like format
by default.  Use
.B "lsblk \-\-help"
to get a list of all available columns.
.PP
The default output, as well as the default output from options like
.B \-\-fs
and
.BR \-\-topology ,
is subject to change.  So whenever possible, you should avoid using default
outputs in your scripts.  Always explicitly define expected columns by using
.B \-\-output
.I columns-list
and
.B \-\-list
in environments where a stable output is required.
.PP
Note that
.B lsblk
might be executed in time when
.B udev
does not have all information about recently added or modified devices yet. In this
case it is recommended to use
.B "udevadm settle"
before lsblk to synchronize with udev.
.SH OPTIONS
.TP
.BR \-a , " \-\-all"
Also list empty devices and RAM disk devices.
.TP
.BR \-b , " \-\-bytes"
Print the SIZE column in bytes rather than in a human-readable format.
.TP
.BR \-D , " \-\-discard"
Print information about the discarding capabilities (TRIM, UNMAP) for each device.
.TP
.BR \-d , " \-\-nodeps"
Do not print holder devices or slaves.  For example, \fBlsblk \-\-nodeps /dev/sda\fR prints
information about the sda device only.
.TP
.BR \-E , " \-\-dedup " \fIcolumn\fP
Use \fIcolumn\fP as a de-duplication key to de-duplicate output tree. If the
key is not available for the device, or the device is a partition and parental
whole-disk device provides the same key than the device is always printed.

The usual use case is to de-duplicate output on system multi-path devices, for
example by \fB\-E WWN\fR.
.TP
.BR \-e , " \-\-exclude " \fIlist\fP
Exclude the devices specified by the comma-separated \fIlist\fR of major device numbers.
Note that RAM disks (major=1) are excluded by default if \fB\-\-all\fR is not specified.
The filter is applied to the top-level devices only. This may be confusing for
\fB\-\-list\fR output format where hierarchy of the devices is not obvious.
.TP
.BR \-f , " \-\-fs"
Output info about filesystems.  This option is equivalent to
.BR \-o\ NAME,FSTYPE,LABEL,UUID,FSAVAIL,FSUSE%,MOUNTPOINT .
The authoritative information about filesystems and raids is provided by the
.BR blkid (8)
command.
.TP
.BR \-h , " \-\-help"
Display help text and exit.
.TP
.BR \-I , " \-\-include " \fIlist\fP
Include devices specified by the comma-separated \fIlist\fR of major device numbers.
The filter is applied to the top-level devices only. This may be confusing for
\fB\-\-list\fR output format where hierarchy of the devices is not obvious.
.TP
.BR \-i , " \-\-ascii"
Use ASCII characters for tree formatting.
.TP
.BR \-J , " \-\-json"
Use JSON output format.  It's strongly recommended to use \fB\-\-output\fR and
also \fB\-\-tree\fR if necessary.
.TP
.BR \-l , " \-\-list"
Produce output in the form of a list. The output does not provide information
about relationships between devices and since version 2.34 every device is
printed only once if \fB\-\-pairs\fR or \fB\-\-raw\fR not specified (the
parsable outputs are maintained in backwardly compatible way).
.TP
.BR \-M , " \-\-merge"
Group parents of sub-trees to provide more readable output for RAIDs and
Multi-path devices. The tree-like output is required.
.TP
.BR \-m , " \-\-perms"
Output info about device owner, group and mode.  This option is equivalent to
.BR \-o\ NAME,SIZE,OWNER,GROUP,MODE .
.TP
.BR \-n , " \-\-noheadings"
Do not print a header line.
.TP
.BR \-o , " \-\-output " \fIlist\fP
Specify which output columns to print.  Use
.B \-\-help
to get a list of all supported columns.  The columns may affect tree-like output.
The default is to use tree for the column 'NAME' (see also \fB\-\-tree\fR).

The default list of columns may be extended if \fIlist\fP is
specified in the format \fI+list\fP (e.g., \fBlsblk \-o +UUID\fP).
.TP
.BR \-O , " \-\-output\-all"
Output all available columns.
.TP
.BR \-P , " \-\-pairs"
Produce output in the form of key="value" pairs.  The output lines are still ordered by
dependencies.  All potentially unsafe characters are hex-escaped (\\x<code>).
.TP
.BR \-p , " \-\-paths"
Print full device paths.
.TP
.BR \-r , " \-\-raw"
Produce output in raw format.  The output lines are still ordered by
dependencies.  All potentially unsafe characters are hex-escaped
(\\x<code>) in the NAME, KNAME, LABEL, PARTLABEL and MOUNTPOINT columns.
.TP
.BR \-S , " \-\-scsi"
Output info about SCSI devices only.  All partitions, slaves and holder devices are ignored.
.TP
.BR \-s , " \-\-inverse"
Print dependencies in inverse order. If the \fB\-\-list\fR output is requested then
the lines are still ordered by dependencies.
.TP
.BR \-T , " \-\-tree" [ =\fIcolumn ]
Force tree-like output format.  If \fIcolumn\fP is specified, then a tree is printed in the column.
The default is NAME column.
.TP
.BR \-t , " \-\-topology"
Output info about block-device topology.
This option is equivalent to
.BR \-o\ NAME,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,SCHED,RQ-SIZE,RA,WSAME .
.TP
.BR \-V , " \-\-version"
Display version information and exit.
.TP
.BR \-x , " \-\-sort " \fIcolumn\fP
Sort output lines by \fIcolumn\fP. This option enables \fB\-\-list\fR output format by default.
It is possible to use the option \fI\-\-tree\fP to force tree-like output and
than the tree branches are sorted by the \fIcolumn\fP.
.TP
.BR \-z , " \-\-zoned"
Print the zone model for each device.
.TP
.BR " \-\-sysroot " \fIdirectory\fP
Gather data for a Linux instance other than the instance from which the lsblk
command is issued.  The specified directory is the system root of the Linux
instance to be inspected.  The real device nodes in the target directory can
be replaced by text files with udev attributes.

.SH EXIT STATUS
.IP 0
success
.IP 1
failure
.IP 32
none of specified devices found
.IP 64
some specified devices found, some not found

.SH ENVIRONMENT
.IP LSBLK_DEBUG=all
enables lsblk debug output.
.IP LIBBLKID_DEBUG=all
enables libblkid debug output.
.IP LIBMOUNT_DEBUG=all
enables libmount debug output.
.IP LIBSMARTCOLS_DEBUG=all
enables libsmartcols debug output.
.IP LIBSMARTCOLS_DEBUG_PADDING=on
use visible padding characters. Requires enabled LIBSMARTCOLS_DEBUG.
.SH NOTES
For partitions, some information (e.g., queue attributes) is inherited from the
parent device.
.PP
The
.B lsblk
command needs to be able to look up each block device by major:minor numbers,
which is done by using
.IR /sys/dev/block .
This sysfs block directory appeared in kernel 2.6.27 (October 2008).
In case of problems with a new enough kernel, check that CONFIG_SYSFS
was enabled at the time of the kernel build.

.SH AUTHORS
.nf
Milan Broz <mbroz@redhat.com>
Karel Zak <kzak@redhat.com>
.fi
.SH SEE ALSO
.BR ls (1),
.BR blkid (8),
.BR findmnt (8)
.SH AVAILABILITY
The lsblk command is part of the util-linux package and is available from
https://www.kernel.org/pub/linux/utils/util-linux/.
Commit	Line	Data
	1	.TH LSBLK 8 "February 2013" "util-linux" "System Administration"
	2	.SH NAME
	3	lsblk \- list block devices
	4	.SH SYNOPSIS
	5	.B lsblk
	6	[options]
	7	.RI [ device ...]
	8	.SH DESCRIPTION
	9	.B lsblk
	10	lists information about all available or the specified block devices. The
	11	.B lsblk
	12	command reads the
	13	.B sysfs
	14	filesystem and
	15	.B udev db
	16	to gather information. If the udev db is not available or lsblk is compiled without udev support than it
	17	tries to read LABELs, UUIDs and filesystem types from the block device. In this case root permissions
	18	are necessary.
	19	.PP
	20	The command prints all block devices (except RAM disks) in a tree-like format
	21	by default. Use
	22	.B "lsblk \-\-help"
	23	to get a list of all available columns.
	24	.PP
	25	The default output, as well as the default output from options like
	26	.B \-\-fs
	27	and
	28	.BR \-\-topology ,
	29	is subject to change. So whenever possible, you should avoid using default
	30	outputs in your scripts. Always explicitly define expected columns by using
	31	.B \-\-output
	32	.I columns-list
	33	and
	34	.B \-\-list
	35	in environments where a stable output is required.
	36	.PP
	37	Note that
	38	.B lsblk
	39	might be executed in time when
	40	.B udev
	41	does not have all information about recently added or modified devices yet. In this
	42	case it is recommended to use
	43	.B "udevadm settle"
	44	before lsblk to synchronize with udev.
	45	.SH OPTIONS
	46	.TP
	47	.BR \-a , " \-\-all"
	48	Also list empty devices and RAM disk devices.
	49	.TP
	50	.BR \-b , " \-\-bytes"
	51	Print the SIZE column in bytes rather than in a human-readable format.
	52	.TP
	53	.BR \-D , " \-\-discard"
	54	Print information about the discarding capabilities (TRIM, UNMAP) for each device.
	55	.TP
	56	.BR \-d , " \-\-nodeps"
	57	Do not print holder devices or slaves. For example, \fBlsblk \-\-nodeps /dev/sda\fR prints
	58	information about the sda device only.
	59	.TP
	60	.BR \-E , " \-\-dedup " \fIcolumn\fP
	61	Use \fIcolumn\fP as a de-duplication key to de-duplicate output tree. If the
	62	key is not available for the device, or the device is a partition and parental
	63	whole-disk device provides the same key than the device is always printed.
	64
	65	The usual use case is to de-duplicate output on system multi-path devices, for
	66	example by \fB\-E WWN\fR.
	67	.TP
	68	.BR \-e , " \-\-exclude " \fIlist\fP
	69	Exclude the devices specified by the comma-separated \fIlist\fR of major device numbers.
	70	Note that RAM disks (major=1) are excluded by default if \fB\-\-all\fR is not specified.
	71	The filter is applied to the top-level devices only. This may be confusing for
	72	\fB\-\-list\fR output format where hierarchy of the devices is not obvious.
	73	.TP
	74	.BR \-f , " \-\-fs"
	75	Output info about filesystems. This option is equivalent to
	76	.BR \-o\ NAME,FSTYPE,LABEL,UUID,FSAVAIL,FSUSE%,MOUNTPOINT .
	77	The authoritative information about filesystems and raids is provided by the
	78	.BR blkid (8)
	79	command.
	80	.TP
	81	.BR \-h , " \-\-help"
	82	Display help text and exit.
	83	.TP
	84	.BR \-I , " \-\-include " \fIlist\fP
	85	Include devices specified by the comma-separated \fIlist\fR of major device numbers.
	86	The filter is applied to the top-level devices only. This may be confusing for
	87	\fB\-\-list\fR output format where hierarchy of the devices is not obvious.
	88	.TP
	89	.BR \-i , " \-\-ascii"
	90	Use ASCII characters for tree formatting.
	91	.TP
	92	.BR \-J , " \-\-json"
	93	Use JSON output format. It's strongly recommended to use \fB\-\-output\fR and
	94	also \fB\-\-tree\fR if necessary.
	95	.TP
	96	.BR \-l , " \-\-list"
	97	Produce output in the form of a list. The output does not provide information
	98	about relationships between devices and since version 2.34 every device is
	99	printed only once if \fB\-\-pairs\fR or \fB\-\-raw\fR not specified (the
	100	parsable outputs are maintained in backwardly compatible way).
	101	.TP
	102	.BR \-M , " \-\-merge"
	103	Group parents of sub-trees to provide more readable output for RAIDs and
	104	Multi-path devices. The tree-like output is required.
	105	.TP
	106	.BR \-m , " \-\-perms"
	107	Output info about device owner, group and mode. This option is equivalent to
	108	.BR \-o\ NAME,SIZE,OWNER,GROUP,MODE .
	109	.TP
	110	.BR \-n , " \-\-noheadings"
	111	Do not print a header line.
	112	.TP
	113	.BR \-o , " \-\-output " \fIlist\fP
	114	Specify which output columns to print. Use
	115	.B \-\-help
	116	to get a list of all supported columns. The columns may affect tree-like output.
	117	The default is to use tree for the column 'NAME' (see also \fB\-\-tree\fR).
	118
	119	The default list of columns may be extended if \fIlist\fP is
	120	specified in the format \fI+list\fP (e.g., \fBlsblk \-o +UUID\fP).
	121	.TP
	122	.BR \-O , " \-\-output\-all"
	123	Output all available columns.
	124	.TP
	125	.BR \-P , " \-\-pairs"
	126	Produce output in the form of key="value" pairs. The output lines are still ordered by
	127	dependencies. All potentially unsafe characters are hex-escaped (\\x<code>).
	128	.TP
	129	.BR \-p , " \-\-paths"
	130	Print full device paths.
	131	.TP
	132	.BR \-r , " \-\-raw"
	133	Produce output in raw format. The output lines are still ordered by
	134	dependencies. All potentially unsafe characters are hex-escaped
	135	(\\x<code>) in the NAME, KNAME, LABEL, PARTLABEL and MOUNTPOINT columns.
	136	.TP
	137	.BR \-S , " \-\-scsi"
	138	Output info about SCSI devices only. All partitions, slaves and holder devices are ignored.
	139	.TP
	140	.BR \-s , " \-\-inverse"
	141	Print dependencies in inverse order. If the \fB\-\-list\fR output is requested then
	142	the lines are still ordered by dependencies.
	143	.TP
	144	.BR \-T , " \-\-tree" [ =\fIcolumn ]
	145	Force tree-like output format. If \fIcolumn\fP is specified, then a tree is printed in the column.
	146	The default is NAME column.
	147	.TP
	148	.BR \-t , " \-\-topology"
	149	Output info about block-device topology.
	150	This option is equivalent to
	151	.BR \-o\ NAME,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,SCHED,RQ-SIZE,RA,WSAME .
	152	.TP
	153	.BR \-V , " \-\-version"
	154	Display version information and exit.
	155	.TP
	156	.BR \-x , " \-\-sort " \fIcolumn\fP
	157	Sort output lines by \fIcolumn\fP. This option enables \fB\-\-list\fR output format by default.
	158	It is possible to use the option \fI\-\-tree\fP to force tree-like output and
	159	than the tree branches are sorted by the \fIcolumn\fP.
	160	.TP
	161	.BR \-z , " \-\-zoned"
	162	Print the zone model for each device.
	163	.TP
	164	.BR " \-\-sysroot " \fIdirectory\fP
	165	Gather data for a Linux instance other than the instance from which the lsblk
	166	command is issued. The specified directory is the system root of the Linux
	167	instance to be inspected. The real device nodes in the target directory can
	168	be replaced by text files with udev attributes.
	169
	170	.SH EXIT STATUS
	171	.IP 0
	172	success
	173	.IP 1
	174	failure
	175	.IP 32
	176	none of specified devices found
	177	.IP 64
	178	some specified devices found, some not found
	179
	180	.SH ENVIRONMENT
	181	.IP LSBLK_DEBUG=all
	182	enables lsblk debug output.
	183	.IP LIBBLKID_DEBUG=all
	184	enables libblkid debug output.
	185	.IP LIBMOUNT_DEBUG=all
	186	enables libmount debug output.
	187	.IP LIBSMARTCOLS_DEBUG=all
	188	enables libsmartcols debug output.
	189	.IP LIBSMARTCOLS_DEBUG_PADDING=on
	190	use visible padding characters. Requires enabled LIBSMARTCOLS_DEBUG.
	191	.SH NOTES
	192	For partitions, some information (e.g., queue attributes) is inherited from the
	193	parent device.
	194	.PP
	195	The
	196	.B lsblk
	197	command needs to be able to look up each block device by major:minor numbers,
	198	which is done by using
	199	.IR /sys/dev/block .
	200	This sysfs block directory appeared in kernel 2.6.27 (October 2008).
	201	In case of problems with a new enough kernel, check that CONFIG_SYSFS
	202	was enabled at the time of the kernel build.
	203
	204	.SH AUTHORS
	205	.nf
	206	Milan Broz <mbroz@redhat.com>
	207	Karel Zak <kzak@redhat.com>
	208	.fi
	209	.SH SEE ALSO
	210	.BR ls (1),
	211	.BR blkid (8),
	212	.BR findmnt (8)
	213	.SH AVAILABILITY
	214	The lsblk command is part of the util-linux package and is available from
	215	https://www.kernel.org/pub/linux/utils/util-linux/.