]>
Commit | Line | Data |
---|---|---|
51410fc6 KZ |
1 | .\" Copyright 2000 Andreas Dilger (adilger@turbolinux.com) |
2 | .\" | |
51410fc6 | 3 | .\" This file may be copied under the terms of the GNU Public License. |
bc88ad1a | 4 | .TH BLKID 8 "March 2013" "util-linux" "System Administration" |
51410fc6 | 5 | .SH NAME |
0791a058 | 6 | blkid \- locate/print block device attributes |
51410fc6 | 7 | .SH SYNOPSIS |
15a74f75 SK |
8 | .IP \fBblkid\fR |
9 | .BI \-\-label " label" | |
bc88ad1a | 10 | | |
15a74f75 | 11 | .BI \-\-uuid " uuid" |
fc7a1669 | 12 | |
15a74f75 SK |
13 | .IP \fBblkid\fR |
14 | .RB [ \-\-no\-encoding | |
15 | .B \-\-garbage\-collect \-\-list\-one \-\-cache\-file | |
02a8a21a | 16 | .IR file ] |
15a74f75 | 17 | .RB [ \-\-output |
02a8a21a | 18 | .IR format ] |
15a74f75 | 19 | .RB [ \-\-match\-tag |
02a8a21a | 20 | .IR tag ] |
15a74f75 | 21 | .RB [ \-\-match\-token |
02a8a21a | 22 | .IR NAME=value ] |
bc88ad1a | 23 | .RI [ device " ...]" |
02a8a21a | 24 | |
15a74f75 SK |
25 | .IP \fBblkid\fR |
26 | .BR \-\-probe " [" \-\-offset | |
02a8a21a | 27 | .IR offset ] |
15a74f75 | 28 | .RB [ \-\-output |
02a8a21a | 29 | .IR format ] |
15a74f75 | 30 | .RB [ \-\-size |
bc88ad1a | 31 | .IR size ] |
15a74f75 | 32 | .RB [ \-\-match\-tag |
7711e215 | 33 | .IR tag ] |
15a74f75 | 34 | .RB [ \-\-match\-types |
4f946f53 | 35 | .IR list ] |
15a74f75 | 36 | .RB [ \-\-usages |
0bdd2f97 | 37 | .IR list ] |
5e91d5dd | 38 | .RB [ \-\-no\-part\-details ] |
bc88ad1a | 39 | .IR device " ..." |
09792910 | 40 | |
15a74f75 SK |
41 | .IP \fBblkid\fR |
42 | .BR \-\-info " [" \-\-output | |
09792910 | 43 | .IR format ] |
15a74f75 | 44 | .RB [ \-\-match\-tag |
09792910 | 45 | .IR tag ] |
bc88ad1a | 46 | .IR device " ..." |
02a8a21a | 47 | |
51410fc6 KZ |
48 | .SH DESCRIPTION |
49 | The | |
50 | .B blkid | |
0791a058 | 51 | program is the command-line interface to working with the |
51410fc6 | 52 | .BR libblkid (3) |
eb024893 | 53 | library. It can determine the type of content (e.g., filesystem or swap) |
bc88ad1a | 54 | that a block device holds, and also the attributes (tokens, NAME=value pairs) |
eb024893 | 55 | from the content metadata (e.g., LABEL or UUID fields). |
51410fc6 | 56 | .PP |
f36522da | 57 | .B It is recommended to use |
9b825f81 | 58 | .BR lsblk (8) |
1c4c6024 | 59 | .B command to get information about block devices, or lsblk \-\-fs to get an overview of filesystems, or |
12786a90 KZ |
60 | .BR findmnt (8) |
61 | .B to search in already mounted filesystems. | |
62 | .PP | |
63 | .RS | |
9b825f81 | 64 | .BR lsblk (8) |
12786a90 KZ |
65 | provides more information, better control on output formatting, easy to use in |
66 | scripts and it does not require root permissions to get actual information. | |
67 | .B blkid | |
68 | reads information directly from devices and for non-root users | |
69 | it returns cached unverified information. | |
70 | .B blkid | |
71 | is mostly designed for system services and to test libblkid functionality. | |
72 | .RE | |
73 | ||
9b825f81 | 74 | .PP |
bc88ad1a BS |
75 | When |
76 | .I device | |
77 | is specified, tokens from only this device are displayed. | |
78 | It is possible to specify multiple | |
79 | .I device | |
80 | arguments on the command line. | |
969e8cbe | 81 | If none is given, all partitions or unpartitioned devices which appear in |
bc88ad1a BS |
82 | .I /proc/partitions |
83 | are shown, if they are recognized. | |
84 | .PP | |
51410fc6 KZ |
85 | .B blkid |
86 | has two main forms of operation: either searching for a device with a | |
87 | specific NAME=value pair, or displaying NAME=value pairs for one or | |
0791a058 | 88 | more specified devices. |
27fbfef3 KZ |
89 | |
90 | For security reasons | |
91 | .B blkid | |
beaca64a | 92 | silently ignores all devices where the probing result is ambivalent (multiple |
1c4c6024 | 93 | colliding filesystems are detected). The low-level probing mode (\fB\-p\fR) |
a87f49f6 | 94 | provides more information and extra exit status in this case. |
27fbfef3 KZ |
95 | It's recommended to use |
96 | .BR wipefs (8) | |
97 | to get a detailed overview and to erase obsolete stuff (magic strings) from the device. | |
98 | ||
51410fc6 | 99 | .SH OPTIONS |
d636d6d8 | 100 | The \fIsize\fR and \fIoffset\fR arguments may be followed by the multiplicative |
bc88ad1a | 101 | suffixes like KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB |
eb024893 | 102 | (the "iB" is optional, e.g., "K" has the same meaning as "KiB"), or the suffixes |
bc88ad1a | 103 | KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB. |
51410fc6 | 104 | .TP |
15a74f75 | 105 | \fB\-c\fR, \fB\-\-cache\-file\fR \fIcachefile\fR |
51410fc6 KZ |
106 | Read from |
107 | .I cachefile | |
bc88ad1a | 108 | instead of reading from the default cache file (see the CONFIGURATION FILE section |
eb024893 | 109 | for more details). If you want to start with a clean cache (i.e., don't report |
b82590ad | 110 | devices previously scanned but not necessarily available at this time), specify |
51410fc6 KZ |
111 | .IR /dev/null . |
112 | .TP | |
15a74f75 | 113 | \fB\-d\fR, \fB\-\-no\-encoding\fR |
bc88ad1a | 114 | Don't encode non-printing characters. The non-printing characters are encoded |
15a74f75 | 115 | by ^ and M- notation by default. Note that the \fB\-\-output udev\fR output format uses |
bc88ad1a | 116 | a different encoding which cannot be disabled. |
36a74e1b | 117 | .TP |
2bb3aa36 | 118 | \fB\-D\fR, \fB\-\-no\-part\-details\fR |
5e91d5dd KZ |
119 | Don't print information (PART_ENTRY_* tags) from partition table in low-level probing mode. |
120 | .TP | |
15a74f75 | 121 | \fB\-g\fR, \fB\-\-garbage\-collect\fR |
51410fc6 KZ |
122 | Perform a garbage collection pass on the blkid cache to remove |
123 | devices which no longer exist. | |
124 | .TP | |
15a74f75 | 125 | \fB\-h\fR, \fB\-\-help\fR |
51410fc6 KZ |
126 | Display a usage message and exit. |
127 | .TP | |
15a74f75 | 128 | \fB\-i\fR, \fB\-\-info\fR |
bc88ad1a | 129 | Display information about I/O Limits (aka I/O topology). The 'export' output format is |
15a74f75 | 130 | automatically enabled. This option can be used together with the \fB\-\-probe\fR option. |
09792910 | 131 | .TP |
15a74f75 | 132 | \fB\-k\fR, \fB\-\-list\-filesystems\fR |
bc88ad1a BS |
133 | List all known filesystems and RAIDs and exit. |
134 | .TP | |
15a74f75 SK |
135 | \fB\-l\fR, \fB\-\-list\-one\fR |
136 | Look up only one device that matches the search parameter specified with the \fB\-\-match\-token\fR | |
51410fc6 KZ |
137 | option. If there are multiple devices that match the specified search |
138 | parameter, then the device with the highest priority is returned, and/or | |
bce4a17b KZ |
139 | the first device found at a given priority (but see below note about udev). |
140 | Device types in order of decreasing priority are: Device Mapper, EVMS, LVM, MD, | |
141 | and finally regular block devices. If this option is not specified, | |
51410fc6 KZ |
142 | .B blkid |
143 | will print all of the devices that match the search parameter. | |
bce4a17b KZ |
144 | .sp |
145 | This option forces | |
146 | .B blkid | |
147 | to use udev when used for LABEL or UUID tokens in \fB\-\-match\-token\fR. The | |
148 | goal is to provide output consistent with another utils (like mount, etc.) | |
149 | on systems where the same tag is used for multiple devices. | |
51410fc6 | 150 | .TP |
15a74f75 | 151 | \fB\-L\fR, \fB\-\-label\fR \fIlabel\fR |
bc88ad1a | 152 | Look up the device that uses this filesystem \fIlabel\fR; this is equal to |
1c4c6024 | 153 | .BR "\-\-list-one \-\-output device \-\-match-token LABEL=\fIlabel\fR" . |
bc88ad1a | 154 | This lookup method is able to reliably use /dev/disk/by-label |
0791a058 BS |
155 | udev symlinks (dependent on a setting in /etc/blkid.conf). Avoid using the |
156 | symlinks directly; it is not reliable to use the symlinks without verification. | |
15a74f75 | 157 | The \fB-\-label\fR option works on systems with and without udev. |
2d71a929 KZ |
158 | |
159 | Unfortunately, the original | |
8323d9fd | 160 | .BR blkid (8) |
1c4c6024 BIG |
161 | from e2fsprogs uses the \fB\-L\fR option as a |
162 | synonym for \fB\-o list\fR. For better portability, use \fB\-l \-o device | |
163 | \-t LABEL=\fIlabel\fR and \fB\-o list\fR in your scripts rather than the \fB\-L\fR option. | |
fc7a1669 | 164 | .TP |
15a74f75 | 165 | \fB\-n\fR, \fB\-\-match\-types\fR \fIlist\fR |
0791a058 BS |
166 | Restrict the probing functions to the specified (comma-separated) \fIlist\fR of |
167 | superblock types (names). | |
168 | The list items may be prefixed with "no" to specify the types which should be ignored. | |
4f946f53 KZ |
169 | For example: |
170 | .sp | |
1c4c6024 | 171 | blkid \-\-probe \-\-match-types vfat,ext3,ext4 /dev/sda1 |
4f946f53 KZ |
172 | .sp |
173 | probes for vfat, ext3 and ext4 filesystems, and | |
174 | .sp | |
1c4c6024 | 175 | blkid \-\-probe \-\-match-types nominix /dev/sda1 |
4f946f53 | 176 | .sp |
0791a058 | 177 | probes for all supported formats except minix filesystems. |
15a74f75 | 178 | This option is only useful together with \fB\-\-probe\fR. |
4f946f53 | 179 | .TP |
15a74f75 | 180 | \fB\-o\fR, \fB\-\-output\fR \fIformat\fR |
bc88ad1a | 181 | Use the specified output format. Note that the order of variables and |
1c4c6024 | 182 | devices is not fixed. See also option \fB\-s\fR. The |
51410fc6 | 183 | .I format |
02a8a21a KZ |
184 | parameter may be: |
185 | .RS | |
51410fc6 | 186 | .TP |
02a8a21a KZ |
187 | .B full |
188 | print all tags (the default) | |
189 | .TP | |
190 | .B value | |
191 | print the value of the tags | |
192 | .TP | |
193 | .B list | |
0791a058 | 194 | print the devices in a user-friendly format; this output format is unsupported |
15a74f75 | 195 | for low-level probing (\fB\-\-probe\fR or \fB\-\-info\fR). |
bc88ad1a BS |
196 | |
197 | This output format is \fBDEPRECATED\fR in favour of the | |
24d741d8 KZ |
198 | .BR lsblk (8) |
199 | command. | |
02a8a21a KZ |
200 | .TP |
201 | .B device | |
15a74f75 SK |
202 | print the device name only; this output format is always enabled for the \fB\-\-label\fR |
203 | and \fB\-\-uuid\fR options | |
02a8a21a KZ |
204 | .TP |
205 | .B udev | |
0791a058 | 206 | print key="value" pairs for easy import into the udev environment; the keys are |
fc402b8b KZ |
207 | prefixed by ID_FS_ or ID_PART_ prefixes. The value may be modified to be |
208 | safe for udev environment; allowed is plain ASCII, hex-escaping and valid UTF-8, | |
209 | everything else (including whitespaces) is replaced with '_'. The keys with | |
210 | _ENC postfix use hex-escaping for unsafe chars. | |
c38b4ebb | 211 | |
0791a058 | 212 | The udev output returns the ID_FS_AMBIVALENT tag if more superblocks are detected, |
c38b4ebb | 213 | and ID_PART_ENTRY_* tags are always returned for all partitions including empty |
fc402b8b KZ |
214 | partitions. |
215 | ||
216 | This output format is \fBDEPRECATED\fR. | |
ab978962 KZ |
217 | .TP |
218 | .B export | |
0791a058 | 219 | print key=value pairs for easy import into the environment; this output format |
15a74f75 | 220 | is automatically enabled when I/O Limits (\fB\-\-info\fR option) are requested. |
89e90ae7 KZ |
221 | |
222 | The non-printing characters are encoded by ^ and M- notation and all | |
223 | potentially unsafe characters are escaped. | |
02a8a21a KZ |
224 | .RE |
225 | .TP | |
15a74f75 SK |
226 | \fB\-O\fR, \fB\-\-offset\fR \fIoffset\fR |
227 | Probe at the given \fIoffset\fR (only useful with \fB\-\-probe\fR). This option can be | |
228 | used together with the \fB\-\-info\fR option. | |
02a8a21a | 229 | .TP |
15a74f75 | 230 | \fB\-p\fR, \fB\-\-probe\fR |
bc88ad1a | 231 | Switch to low-level superblock probing mode (bypassing the cache). |
c38b4ebb KZ |
232 | |
233 | Note that low-level probing also returns information about partition table type | |
f36522da KZ |
234 | (PTTYPE tag) and partitions (PART_ENTRY_* tags). The tag names produced by |
235 | low-level probing are based on names used internally by libblkid and it may be | |
15a74f75 | 236 | different than when executed without \fB\-\-probe\fR (for example PART_ENTRY_UUID= vs |
5e91d5dd | 237 | PARTUUID=). See also \fB\-\-no\-part\-details\fR. |
51410fc6 | 238 | .TP |
15a74f75 | 239 | \fB\-s\fR, \fB\-\-match\-tag\fR \fItag\fR |
51410fc6 KZ |
240 | For each (specified) device, show only the tags that match |
241 | .IR tag . | |
242 | It is possible to specify multiple | |
15a74f75 | 243 | .B \-\-match\-tag |
51410fc6 KZ |
244 | options. If no tag is specified, then all tokens are shown for all |
245 | (specified) devices. | |
246 | In order to just refresh the cache without showing any tokens, use | |
15a74f75 | 247 | .B "\-\-match\-tag none" |
51410fc6 KZ |
248 | with no other options. |
249 | .TP | |
15a74f75 SK |
250 | \fB\-S\fR, \fB\-\-size\fR \fIsize\fR |
251 | Override the size of device/file (only useful with \fB\-\-probe\fR). | |
02a8a21a | 252 | .TP |
15a74f75 | 253 | \fB\-t\fR, \fB\-\-match\-token\fR \fINAME=value\fR |
51410fc6 KZ |
254 | Search for block devices with tokens named |
255 | .I NAME | |
256 | that have the value | |
257 | .IR value , | |
258 | and display any devices which are found. | |
259 | Common values for | |
260 | .I NAME | |
261 | include | |
262 | .BR TYPE , | |
263 | .BR LABEL , | |
264 | and | |
265 | .BR UUID . | |
266 | If there are no devices specified on the command line, all block devices | |
267 | will be searched; otherwise only the specified devices are searched. | |
268 | .TP | |
15a74f75 | 269 | \fB\-u\fR, \fB\-\-usages\fR \fIlist\fR |
0791a058 BS |
270 | Restrict the probing functions to the specified (comma-separated) \fIlist\fR of "usage" types. |
271 | Supported usage types are: filesystem, raid, crypto and other. The list items may be | |
272 | prefixed with "no" to specify the usage types which should be ignored. For example: | |
8ab43e6a | 273 | .sp |
1c4c6024 | 274 | blkid \-\-probe \-\-usages filesystem,other /dev/sda1 |
8ab43e6a | 275 | .sp |
eb024893 | 276 | probes for all filesystem and other (e.g., swap) formats, and |
8ab43e6a | 277 | .sp |
1c4c6024 | 278 | blkid \-\-probe \-\-usages noraid /dev/sda1 |
8ab43e6a | 279 | .sp |
0791a058 | 280 | probes for all supported formats except RAIDs. |
15a74f75 | 281 | This option is only useful together with \fB\-\-probe\fR. |
8ab43e6a | 282 | .TP |
15a74f75 SK |
283 | \fB\-U\fR, \fB\-\-uuid\fR \fIuuid\fR |
284 | Look up the device that uses this filesystem \fIuuid\fR. For more details see the | |
285 | \fB\-\-label\fR option. | |
8ab43e6a | 286 | .TP |
15a74f75 | 287 | \fB\-V\fR, \fB\-\-version\fR |
51410fc6 | 288 | Display version number and exit. |
7e765c93 | 289 | .SH EXIT STATUS |
f36522da | 290 | If the specified device or device addressed by specified token (option |
15a74f75 | 291 | \fB\-\-match\-token\fR) was found and it's possible to gather any information about the |
a87f49f6 MK |
292 | device, an exit status 0 is returned. Note the option \fB\-\-match\-tag\fR filters output |
293 | tags, but it does not affect exit status. | |
68c88d94 KZ |
294 | |
295 | If the specified token was not found, or no (specified) devices could be | |
5bf5752e | 296 | identified, or it is impossible to gather any information about the device |
a87f49f6 | 297 | identifiers or device content an exit status of 2 is returned. |
68c88d94 | 298 | |
a87f49f6 | 299 | For usage or other errors, an exit status of 4 is returned. |
68c88d94 | 300 | |
a87f49f6 | 301 | If an ambivalent probing result was detected by low-level probing mode (\fB\-p\fR), an exit status of 8 is |
68c88d94 | 302 | returned. |
b82590ad KZ |
303 | .SH CONFIGURATION FILE |
304 | The standard location of the | |
305 | .I /etc/blkid.conf | |
306 | config file can be overridden by the environment variable BLKID_CONF. | |
307 | The following options control the libblkid library: | |
308 | .TP | |
309 | .I SEND_UEVENT=<yes|not> | |
310 | Sends uevent when | |
10b4d34d | 311 | .I /dev/disk/by-{label,uuid,partuuid,partlabel}/ |
bc88ad1a | 312 | symlink does not match with LABEL, UUID, PARTUUID or PARTLABEL on the device. Default is "yes". |
b82590ad KZ |
313 | .TP |
314 | .I CACHE_FILE=<path> | |
bc88ad1a BS |
315 | Overrides the standard location of the cache file. This setting can be |
316 | overridden by the environment variable BLKID_FILE. Default is | |
317 | .IR /run/blkid/blkid.tab , | |
b82590ad KZ |
318 | or |
319 | .I /etc/blkid.tab | |
bc88ad1a | 320 | on systems without a /run directory. |
b82590ad KZ |
321 | .TP |
322 | .I EVALUATE=<methods> | |
bc88ad1a BS |
323 | Defines LABEL and UUID evaluation method(s). Currently, the libblkid library |
324 | supports the "udev" and "scan" methods. More than one method may be specified in | |
325 | a comma-separated list. Default is "udev,scan". The "udev" method uses udev | |
b82590ad KZ |
326 | .I /dev/disk/by-* |
327 | symlinks and the "scan" method scans all block devices from the | |
328 | .I /proc/partitions | |
329 | file. | |
a8d0d330 | 330 | .SH AUTHORS |
51410fc6 | 331 | .B blkid |
02a8a21a KZ |
332 | was written by Andreas Dilger for libblkid and improved by Theodore Ts'o |
333 | and Karel Zak. | |
ddfeda98 | 334 | .SH ENVIRONMENT |
68e422ec | 335 | .IP "Setting LIBBLKID_DEBUG=all enables debug output." |
9c91fc03 | 336 | .SH SEE ALSO |
66083665 MF |
337 | .BR libblkid (3), |
338 | .BR findfs (8), | |
9b825f81 | 339 | .BR lsblk (8), |
f053ff1e | 340 | .BR wipefs (8) |
9c91fc03 BS |
341 | .SH AVAILABILITY |
342 | The blkid command is part of the util-linux package and is available from | |
d673b74e | 343 | https://www.kernel.org/pub/linux/utils/util-linux/. |