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