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

.\" -*- nroff -*-
.TH LSBLK 8 "February 2013" "util-linux" "System Administration"
.SH NAME
lsblk \- list block devices
.SH SYNOPSIS
.B lsblk
.RB [ options ]
.RI [ device ...]
.SH DESCRIPTION
.B lsblk
lists information about all available or the specified block devices.  The
.B lsblk
command reads the
.I sysfs
filesystem to gather information.
.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
.BR \-\-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
in environments where a stable output is required.
.SH OPTIONS
.TP
.BR \-a , " \-\-all"
Also list empty devices.  (By default they are skipped.)
.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 , " \-\-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.  The filter is applied to the
top-level devices only.
.TP
.BR \-f , " \-\-fs"
Output info about filesystems.  This option is equivalent to
.BR -o\ NAME,FSTYPE,LABEL,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.
.TP
.BR \-i , " \-\-ascii"
Use ASCII characters for tree formatting.
.TP
.BR \-l , " \-\-list"
Produce output in the form of a list.
.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 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 \-P , " \-\-pairs"
Produce output in the form of key="value" pairs.
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.  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.
.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,WSAME .
.TP
.BR \-V , " \-\-version"
Display version information and exit.
.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
.BR /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 ENVIRONMENT
.IP "Setting LIBMOUNT_DEBUG=0xffff enables debug output."
.SH SEE ALSO
.BR findmnt (8),
.BR blkid (8),
.BR ls (1)
.SH AVAILABILITY
The lsblk command is part of the util-linux package and is available from
ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
Commit	Line	Data
2a4c734b	1	.\" -- nroff --
ceefa682	2	.TH LSBLK 8 "February 2013" "util-linux" "System Administration"
2a4c734b MB	3	.SH NAME
	4	lsblk \- list block devices
	5	.SH SYNOPSIS
	6	.B lsblk
	7	.RB [ options ]
ceefa682	8	.RI [ device ...]
2a4c734b MB	9	.SH DESCRIPTION
2a4c734b MB	10	.B lsblk
ceefa682	11	lists information about all available or the specified block devices. The
2a4c734b	12	.B lsblk
8d7f2904	13	command reads the
2a4c734b MB	14	.I sysfs
	15	filesystem to gather information.
	16	.PP
8d7f2904 BS	17	The command prints all block devices (except RAM disks) in a tree-like format
8d7f2904 BS	18	by default. Use
2a4c734b	19	.B "lsblk --help"
8d7f2904	20	to get a list of all available columns.
980358f1	21	.PP
ceefa682 BS	22	The default output, as well as the default output from options like
	23	.BR \-\-fs
	24	and
	25	.BR \-\-topology ,
	26	is subject to change. So whenever possible, you should avoid using default
	27	outputs in your scripts. Always explicitly define expected columns by using
980358f1	28	.B \-\-output
ceefa682 BS	29	.I columns-list
ceefa682 BS	30	in environments where a stable output is required.
2a4c734b	31	.SH OPTIONS
ceefa682 BS	32	.TP
	33	.BR \-a , " \-\-all"
	34	Also list empty devices. (By default they are skipped.)
	35	.TP
	36	.BR \-b , " \-\-bytes"
	37	Print the SIZE column in bytes rather than in a human-readable format.
	38	.TP
	39	.BR \-D , " \-\-discard"
	40	Print information about the discarding capabilities (TRIM, UNMAP) for each device.
	41	.TP
	42	.BR \-d , " \-\-nodeps"
	43	Do not print holder devices or slaves. For example, \fBlsblk --nodeps /dev/sda\fR prints
f31505fe	44	information about the sda device only.
ceefa682 BS	45	.TP
	46	.BR \-e , " \-\-exclude " \fIlist\fP
	47	Exclude the devices specified by the comma-separated \fIlist\fR of major device numbers.
	48	Note that RAM disks (major=1) are excluded by default. The filter is applied to the
	49	top-level devices only.
	50	.TP
	51	.BR \-f , " \-\-fs"
	52	Output info about filesystems. This option is equivalent to
	53	.BR -o\ NAME,FSTYPE,LABEL,MOUNTPOINT .
8d7f2904	54	The authoritative information about filesystems and raids is provided by the
2a4c734b MB	55	.BR blkid (8)
2a4c734b MB	56	command.
ceefa682 BS	57	.TP
ceefa682 BS	58	.BR \-h , " \-\-help"
b4362b6f	59	Display help text and exit.
ceefa682 BS	60	.TP
	61	.BR \-I , " \-\-include " \fIlist\fP
	62	Include devices specified by the comma-separated \fIlist\fR of major device numbers.
	63	The filter is applied to the top-level devices only.
	64	.TP
	65	.BR \-i , " \-\-ascii"
6ea1bdd3	66	Use ASCII characters for tree formatting.
ceefa682 BS	67	.TP
	68	.BR \-l , " \-\-list"
	69	Produce output in the form of a list.
	70	.TP
	71	.BR \-m , " \-\-perms"
	72	Output info about device owner, group and mode. This option is equivalent to
	73	.BR -o\ NAME,SIZE,OWNER,GROUP,MODE .
	74	.TP
	75	.BR \-n , " \-\-noheadings"
2a4c734b	76	Do not print a header line.
ceefa682 BS	77	.TP
ceefa682 BS	78	.BR \-o , " \-\-output " \fIlist\fP
8d7f2904	79	Specify which output columns to print. Use
ceefa682	80	.B \-\-help
8d7f2904	81	to get a list of all supported columns.
36fb1007	82
37684203 BS	83	The default list of columns may be extended if \fIlist\fP is
37684203 BS	84	specified in the format \fI+list\fP (e.g. \fBlsblk -o +UUID\fP).
ceefa682 BS	85	.TP
	86	.BR \-P , " \-\-pairs"
	87	Produce output in the form of key="value" pairs.
	88	All potentially unsafe characters are hex-escaped (\\x<code>).
	89	.TP
c7e76cd1 KZ	90	.BR \-p , " \-\-paths"
	91	Print full device paths.
	92	.TP
ceefa682 BS	93	.BR \-r , " \-\-raw"
	94	Produce output in raw format. All potentially unsafe characters are hex-escaped
	95	(\\x<code>) in the NAME, KNAME, LABEL, PARTLABEL and MOUNTPOINT columns.
	96	.TP
	97	.BR \-S , " \-\-scsi"
	98	Output info about SCSI devices only. All partitions, slaves and holder devices are ignored.
	99	.TP
	100	.BR \-s , " \-\-inverse"
8265242b	101	Print dependencies in inverse order.
ceefa682 BS	102	.TP
	103	.BR \-t , " \-\-topology"
	104	Output info about block-device topology.
	105	This option is equivalent to
	106	.BR -o\ NAME,ALIGNMENT,MIN-IO,OPT-IO,PHY-SEC,LOG-SEC,ROTA,SCHED,RQ-SIZE,WSAME .
	107	.TP
	108	.BR \-V , " \-\-version"
b4362b6f	109	Display version information and exit.
9830eca5	110	.SH NOTES
68eebd53 PU	111	For partitions, some information (e.g. queue attributes) is inherited from the
68eebd53 PU	112	parent device.
f65b3bb6 SK	113	.PP
	114	The
	115	.B lsblk
ceefa682 BS	116	command needs to be able to look up each block device by major:minor numbers,
ceefa682 BS	117	which is done by using
f65b3bb6	118	.BR /sys/dev/block .
ceefa682 BS	119	This sysfs block directory appeared in kernel 2.6.27 (October 2008).
	120	In case of problems with a new enough kernel, check that CONFIG_SYSFS
	121	was enabled at the time of the kernel build.
2a4c734b MB	122	.SH AUTHORS
	123	.nf
	124	Milan Broz <mbroz@redhat.com>
	125	Karel Zak <kzak@redhat.com>
	126	.fi
ca3dbca1	127	.SH ENVIRONMENT
ceefa682	128	.IP "Setting LIBMOUNT_DEBUG=0xffff enables debug output."
2a4c734b MB	129	.SH SEE ALSO
	130	.BR findmnt (8),
	131	.BR blkid (8),
	132	.BR ls (1)
	133	.SH AVAILABILITY
601d12fb KZ	134	The lsblk command is part of the util-linux package and is available from
601d12fb KZ	135	ftp://ftp.kernel.org/pub/linux/utils/util-linux/.