Debian Codegraph @

upstream/debian-trixie/man8/udevadm.8

raw
1 '\" t
2 .TH "UDEVADM" "8" "" "systemd 257.13" "udevadm"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 udevadm \- udev management tool
24 .SH "SYNOPSIS"
25 .HP \w'\fBudevadm\fR\ 'u
26 \fBudevadm\fR [\fB\-\-debug\fR] [\fB\-\-version\fR] [\fB\-\-help\fR]
27 .HP \w'\fBudevadm\ info\ \fR\fB[options]\fR\fB\ \fR\fB[devpath]\fR\ 'u
28 \fBudevadm info \fR\fB[options]\fR\fB \fR\fB[devpath]\fR
29 .HP \w'\fBudevadm\ trigger\ \fR\fB[options]\fR\fB\ \fR\fB[devpath]\fR\ 'u
30 \fBudevadm trigger \fR\fB[options]\fR\fB \fR\fB[devpath]\fR
31 .HP \w'\fBudevadm\ settle\ \fR\fB[options]\fR\ 'u
32 \fBudevadm settle \fR\fB[options]\fR
33 .HP \w'\fBudevadm\ control\ \fR\fB\fIoption\fR\fR\ 'u
34 \fBudevadm control \fR\fB\fIoption\fR\fR
35 .HP \w'\fBudevadm\ monitor\ \fR\fB[options]\fR\ 'u
36 \fBudevadm monitor \fR\fB[options]\fR
37 .HP \w'\fBudevadm\ test\ \fR\fB[options]\fR\fB\ \fR\fB\fIdevpath\fR\fR\ 'u
38 \fBudevadm test \fR\fB[options]\fR\fB \fR\fB\fIdevpath\fR\fR
39 .HP \w'\fBudevadm\ test\-builtin\ \fR\fB[options]\fR\fB\ \fR\fB\fIcommand\fR\fR\fB\ \fR\fB\fIdevpath\fR\fR\ 'u
40 \fBudevadm test\-builtin \fR\fB[options]\fR\fB \fR\fB\fIcommand\fR\fR\fB \fR\fB\fIdevpath\fR\fR
41 .HP \w'\fBudevadm\ verify\fR\ 'u
42 \fBudevadm verify\fR [options...] [\fIfile\fR...]
43 .HP \w'\fBudevadm\ wait\ \fR\fB[options]\fR\fB\ \fR\fB\fIdevice|syspath\fR\fR\ 'u
44 \fBudevadm wait \fR\fB[options]\fR\fB \fR\fB\fIdevice|syspath\fR\fR
45 .HP \w'\fBudevadm\ lock\ \fR\fB[options]\fR\fB\ \fR\fB\fIcommand\fR\fR\ 'u
46 \fBudevadm lock \fR\fB[options]\fR\fB \fR\fB\fIcommand\fR\fR
47 .SH "DESCRIPTION"
48 .PP
49 \fBudevadm\fR
50 expects a command and command specific options\&. It controls the runtime behavior of
51 \fBsystemd\-udevd\fR, requests kernel events, manages the event queue, and provides simple debugging mechanisms\&.
52 .SH "OPTIONS"
53 .PP
54 \fB\-d\fR, \fB\-\-debug\fR
55 .RS 4
56 Print debug messages to standard error\&. This option is implied in
57 \fBudevadm test\fR
58 and
59 \fBudevadm test\-builtin\fR
60 commands\&.
61 .RE
62 .PP
63 \fB\-h\fR, \fB\-\-help\fR
64 .RS 4
65 Print a short help text and exit\&.
66 .RE
67 .SS "udevadm info [\fIoptions\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]"
68 .PP
69 Query the udev database for device information\&.
70 .PP
71 Positional arguments should be used to specify one or more devices\&. Each one may be a device name (in which case it must start with
72 /dev/), a sys path (in which case it must start with
73 /sys/), or a systemd device unit name (in which case it must end with
74 "\&.device", see
75 \fBsystemd.device\fR(5))\&.
76 .PP
77 \fB\-q\fR, \fB\-\-query=\fR\fB\fITYPE\fR\fR
78 .RS 4
79 Query the database for the specified type of device data\&. Valid
80 \fITYPE\fRs are:
81 \fBname\fR,
82 \fBsymlink\fR,
83 \fBpath\fR,
84 \fBproperty\fR,
85 \fBall\fR\&.
86 .RE
87 .PP
88 \fB\-\-property=\fR\fB\fINAME\fR\fR
89 .RS 4
90 When showing device properties using the
91 \fB\-\-query=property\fR
92 option, limit display to properties specified in the argument\&. The argument should be a comma\-separated list of property names\&. If not specified, all known properties are shown\&.
93 .sp
94 Added in version 250\&.
95 .RE
96 .PP
97 \fB\-\-value\fR
98 .RS 4
99 When showing device properties using the
100 \fB\-\-query=property\fR
101 option, print only their values, and skip the property name and
102 "="\&.
103 .sp
104 Cannot be used together with
105 \fB\-x/\-\-export\fR
106 or
107 \fB\-P/\-\-export\-prefix\fR\&.
108 .sp
109 Added in version 250\&.
110 .RE
111 .PP
112 \fB\-p\fR, \fB\-\-path=\fR\fB\fIDEVPATH\fR\fR
113 .RS 4
114 The
115 /sys/
116 path of the device to query, e\&.g\&.
117 [/sys/]/class/block/sda\&. This option is an alternative to the positional argument with a
118 /sys/
119 prefix\&.
120 \fBudevadm info \-\-path=/class/block/sda\fR
121 is equivalent to
122 \fBudevadm info /sys/class/block/sda\fR\&.
123 .RE
124 .PP
125 \fB\-n\fR, \fB\-\-name=\fR\fB\fIFILE\fR\fR
126 .RS 4
127 The name of the device node or a symlink to query, e\&.g\&.
128 [/dev/]/sda\&. This option is an alternative to the positional argument with a
129 /dev/
130 prefix\&.
131 \fBudevadm info \-\-name=sda\fR
132 is equivalent to
133 \fBudevadm info /dev/sda\fR\&.
134 .RE
135 .PP
136 \fB\-r\fR, \fB\-\-root\fR
137 .RS 4
138 Print absolute paths in
139 \fBname\fR
140 or
141 \fBsymlink\fR
142 query\&.
143 .RE
144 .PP
145 \fB\-a\fR, \fB\-\-attribute\-walk\fR
146 .RS 4
147 Print all sysfs properties of the specified device that can be used in udev rules to match the specified device\&. It prints all devices along the chain, up to the root of sysfs that can be used in udev rules\&.
148 .sp
149 This switch supports JSON output mode (see
150 \fB\-\-json=\fR
151 below)\&. Note that because this switch generates multiple JSON objects, JSON\-SEQ mode is automatically enabled (RFC7464)\&. (Note: tools such as
152 \m[blue]\fBjq\fR\m[]\&\s-2\u[1]\d\s+2
153 natively support JSON\-SEQ via the
154 \fB\-\-seq\fR
155 switch\&.)
156 .RE
157 .PP
158 \fB\-t\fR, \fB\-\-tree\fR
159 .RS 4
160 Display a sysfs tree\&. This recursively iterates through the sysfs hierarchy and displays it in a tree structure\&. If a path is specified only the subtree below and its parent directories are shown\&. This will show both device and subsystem items\&.
161 .sp
162 Added in version 251\&.
163 .RE
164 .PP
165 \fB\-x\fR, \fB\-\-export\fR
166 .RS 4
167 Print output as key/value pairs\&. Values are enclosed in single quotes\&. This takes effects only when
168 \fB\-\-query=property\fR
169 or
170 \fB\-\-device\-id\-of\-file=\fR\fB\fIFILE\fR\fR
171 is specified\&.
172 .RE
173 .PP
174 \fB\-P\fR, \fB\-\-export\-prefix=\fR\fB\fINAME\fR\fR
175 .RS 4
176 Add a prefix to the key name of exported values\&. This implies
177 \fB\-\-export\fR\&.
178 .RE
179 .PP
180 \fB\-d\fR, \fB\-\-device\-id\-of\-file=\fR\fB\fIFILE\fR\fR
181 .RS 4
182 Print major/minor numbers of the underlying device, where the file lives on\&. If this is specified, all positional arguments are ignored\&.
183 .RE
184 .PP
185 \fB\-e\fR, \fB\-\-export\-db\fR
186 .RS 4
187 Export the content of the udev database\&.
188 .RE
189 .PP
190 \fB\-c\fR, \fB\-\-cleanup\-db\fR
191 .RS 4
192 Cleanup the udev database\&.
193 .RE
194 .PP
195 \fB\-w\fR\fB[SECONDS]\fR, \fB\-\-wait\-for\-initialization\fR\fB[=SECONDS]\fR
196 .RS 4
197 Wait for device to be initialized\&. If argument
198 \fISECONDS\fR
199 is not specified, the default is to wait forever\&.
200 .sp
201 Added in version 243\&.
202 .RE
203 .PP
204 \fB\-\-subsystem\-match\fR\fB[=SUBSYSTEM]\fR, \fB\-\-subsystem\-nomatch\fR\fB[=SUBSYSTEM]\fR
205 .RS 4
206 When used with
207 \fB\-\-export\-db\fR, only show devices of or not of the given subsystem respectively\&.
208 .sp
209 Added in version 255\&.
210 .RE
211 .PP
212 \fB\-\-attr\-match\fR\fB[=FILE[=VALUE]]\fR, \fB\-\-attr\-nomatch\fR\fB[=FILE[=VALUE]]\fR
213 .RS 4
214 When used with
215 \fB\-\-export\-db\fR, only show devices matching or not matching the given attribute respectively\&.
216 .sp
217 Added in version 255\&.
218 .RE
219 .PP
220 \fB\-\-property\-match\fR\fB[=KEY=VALUE]\fR
221 .RS 4
222 When used with
223 \fB\-\-export\-db\fR, only show devices matching the given property and value\&.
224 .sp
225 Added in version 255\&.
226 .RE
227 .PP
228 \fB\-\-tag\-match\fR\fB[=TAG]\fR
229 .RS 4
230 When used with
231 \fB\-\-export\-db\fR, only show devices with the given tag\&.
232 .sp
233 Added in version 255\&.
234 .RE
235 .PP
236 \fB\-\-sysname\-match\fR\fB[=NAME]\fR
237 .RS 4
238 When used with
239 \fB\-\-export\-db\fR, only show devices with the given
240 "/sys"
241 path\&.
242 .sp
243 Added in version 255\&.
244 .RE
245 .PP
246 \fB\-\-name\-match\fR\fB[=NAME]\fR
247 .RS 4
248 When used with
249 \fB\-\-export\-db\fR, only show devices with the given name in
250 "/dev"\&.
251 .sp
252 Added in version 255\&.
253 .RE
254 .PP
255 \fB\-\-parent\-match\fR\fB[=NAME]\fR
256 .RS 4
257 When used with
258 \fB\-\-export\-db\fR, only show devices with the given parent device\&.
259 .sp
260 Added in version 255\&.
261 .RE
262 .PP
263 \fB\-\-initialized\-match\fR, \fB\-\-initialized\-nomatch\fR
264 .RS 4
265 When used with
266 \fB\-\-export\-db\fR, only show devices that are initialized or not initialized respectively\&.
267 .sp
268 Added in version 255\&.
269 .RE
270 .PP
271 \fB\-\-json=\fR\fB\fIMODE\fR\fR
272 .RS 4
273 Shows output formatted as JSON\&. Expects one of
274 "short"
275 (for the shortest possible output without any redundant whitespace or line breaks),
276 "pretty"
277 (for a pretty version of the same, with indentation and line breaks) or
278 "off"
279 (to turn off JSON output, the default)\&.
280 .RE
281 .PP
282 \fB\-h\fR, \fB\-\-help\fR
283 .RS 4
284 Print a short help text and exit\&.
285 .RE
286 .PP
287 \fB\-\-no\-pager\fR
288 .RS 4
289 Do not pipe output into a pager\&.
290 .RE
291 .PP
292 The generated output shows the current device database entry in a terse format\&. Each line shown is prefixed with one of the following characters:
293 .sp
294 .it 1 an-trap
295 .nr an-no-space-flag 1
296 .nr an-break-flag 1
297 .br
298 .B Table\ \&1.\ \&udevadm info output prefixes
299 .TS
300 allbox tab(:);
301 lB lB.
302 T{
303 Prefix
304 T}:T{
305 Meaning
306 T}
307 .T&
308 l l
309 l l
310 l l
311 l l
312 l l
313 l l
314 l l
315 l l
316 l l
317 l l
318 l l
319 l l
320 l l
321 l l
322 l l.
323 T{
324 "P:"
325 T}:T{
326 Device path in /sys/
327 T}
328 T{
329 "M:"
330 T}:T{
331 Device name in /sys/ (i\&.e\&. the last component of "P:")
332 T}
333 T{
334 "R:"
335 T}:T{
336 Device number in /sys/ (i\&.e\&. the numeric suffix of the last component of "P:")
337 T}
338 T{
339 "J:"
340 T}:T{
341 Device ID
342 T}
343 T{
344 "U:"
345 T}:T{
346 Kernel subsystem
347 T}
348 T{
349 "B:"
350 T}:T{
351 Driver subsystem
352 T}
353 T{
354 "T:"
355 T}:T{
356 Kernel device type within subsystem
357 T}
358 T{
359 "D:"
360 T}:T{
361 Kernel device node major/minor
362 T}
363 T{
364 "I:"
365 T}:T{
366 Network interface index
367 T}
368 T{
369 "N:"
370 T}:T{
371 Kernel device node name
372 T}
373 T{
374 "L:"
375 T}:T{
376 Device node symlink priority
377 T}
378 T{
379 "S:"
380 T}:T{
381 Device node symlink
382 T}
383 T{
384 "Q:"
385 T}:T{
386 Block device sequence number (DISKSEQ)
387 T}
388 T{
389 "V:"
390 T}:T{
391 Attached driver
392 T}
393 T{
394 "E:"
395 T}:T{
396 Device property
397 T}
398 .TE
399 .sp 1
400 .SS "udevadm trigger [\fIoptions\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]"
401 .PP
402 Request device events from the kernel\&. Primarily used to replay events at system coldplug time\&.
403 .PP
404 Takes device specifications as positional arguments\&. See the description of
405 \fBinfo\fR
406 above\&.
407 .PP
408 \fB\-v\fR, \fB\-\-verbose\fR
409 .RS 4
410 Print the list of devices which will be triggered\&.
411 .RE
412 .PP
413 \fB\-n\fR, \fB\-\-dry\-run\fR
414 .RS 4
415 Do not actually trigger the event\&.
416 .RE
417 .PP
418 \fB\-q\fR, \fB\-\-quiet\fR
419 .RS 4
420 Suppress error logging in triggering events\&.
421 .sp
422 Added in version 248\&.
423 .RE
424 .PP
425 \fB\-t\fR, \fB\-\-type=\fR\fB\fITYPE\fR\fR
426 .RS 4
427 Trigger a specific type of devices\&. Valid types are
428 "all",
429 "devices", and
430 "subsystems"\&. The default value is
431 "devices"\&.
432 .RE
433 .PP
434 \fB\-c\fR, \fB\-\-action=\fR\fB\fIACTION\fR\fR
435 .RS 4
436 Type of event to be triggered\&. Possible actions are
437 "add",
438 "remove",
439 "change",
440 "move",
441 "online",
442 "offline",
443 "bind", and
444 "unbind"\&. Also, the special value
445 "help"
446 can be used to list the possible actions\&. The default value is
447 "change"\&.
448 .RE
449 .PP
450 \fB\-\-prioritized\-subsystem=\fR\fB\fISUBSYSTEM\fR\fI[,\fISUBSYSTEM\fR\&...]\fR\fR
451 .RS 4
452 Takes a comma separated list of subsystems\&. When triggering events for devices, the devices from the specified subsystems and their parents are triggered first\&. For example, if
453 \fB\-\-prioritized\-subsystem=block,net\fR, then firstly all block devices and their parents are triggered, in the next all network devices and their parents are triggered, and lastly the other devices are triggered\&. This option can be specified multiple times, and in that case the lists of the subsystems will be merged\&. That is,
454 \fB\-\-prioritized\-subsystem=block \-\-prioritized\-subsystem=net\fR
455 is equivalent to
456 \fB\-\-prioritized\-subsystem=block,net\fR\&.
457 .sp
458 Added in version 251\&.
459 .RE
460 .PP
461 \fB\-s\fR, \fB\-\-subsystem\-match=\fR\fB\fISUBSYSTEM\fR\fR
462 .RS 4
463 Trigger events for devices which belong to a matching subsystem\&. This option supports shell style pattern matching\&. When this option is specified more than once, then each matching result is ORed, that is, all the devices in each subsystem are triggered\&.
464 .RE
465 .PP
466 \fB\-S\fR, \fB\-\-subsystem\-nomatch=\fR\fB\fISUBSYSTEM\fR\fR
467 .RS 4
468 Do not trigger events for devices which belong to a matching subsystem\&. This option supports shell style pattern matching\&. When this option is specified more than once, then each matching result is ANDed, that is, devices which do not match all specified subsystems are triggered\&.
469 .RE
470 .PP
471 \fB\-a\fR, \fB\-\-attr\-match=\fR\fB\fIATTRIBUTE\fR\fR\fB=\fR\fB\fIVALUE\fR\fR
472 .RS 4
473 Trigger events for devices with a matching sysfs attribute\&. If a value is specified along with the attribute name, the content of the attribute is matched against the given value using shell style pattern matching\&. If no value is specified, the existence of the sysfs attribute is checked\&. When this option is specified multiple times, then each matching result is ANDed, that is, only devices which have all specified attributes are triggered\&.
474 .RE
475 .PP
476 \fB\-A\fR, \fB\-\-attr\-nomatch=\fR\fB\fIATTRIBUTE\fR\fR\fB=\fR\fB\fIVALUE\fR\fR
477 .RS 4
478 Do not trigger events for devices with a matching sysfs attribute\&. If a value is specified along with the attribute name, the content of the attribute is matched against the given value using shell style pattern matching\&. If no value is specified, the existence of the sysfs attribute is checked\&. When this option is specified multiple times, then each matching result is ANDed, that is, only devices which have none of the specified attributes are triggered\&.
479 .RE
480 .PP
481 \fB\-p\fR, \fB\-\-property\-match=\fR\fB\fIPROPERTY\fR\fR\fB=\fR\fB\fIVALUE\fR\fR
482 .RS 4
483 Trigger events for devices with a matching property value\&. This option supports shell style pattern matching\&. When this option is specified more than once, then each matching result is ORed, that is, devices which have one of the specified properties are triggered\&.
484 .RE
485 .PP
486 \fB\-g\fR, \fB\-\-tag\-match=\fR\fB\fITAG\fR\fR
487 .RS 4
488 Trigger events for devices with a matching tag\&. When this option is specified multiple times, then each matching result is ANDed, that is, devices which have all specified tags are triggered\&.
489 .RE
490 .PP
491 \fB\-y\fR, \fB\-\-sysname\-match=\fR\fB\fINAME\fR\fR
492 .RS 4
493 Trigger events for devices for which the last component (i\&.e\&. the filename) of the
494 /sys/
495 path matches the specified
496 \fIPATH\fR\&. This option supports shell style pattern matching\&. When this option is specified more than once, then each matching result is ORed, that is, all devices which have any of the specified
497 \fINAME\fR
498 are triggered\&.
499 .RE
500 .PP
501 \fB\-\-name\-match=\fR\fB\fINAME\fR\fR
502 .RS 4
503 Trigger events for devices with a matching device path\&. When this option is specified more than once, then each matching result is ORed, that is, all specified devices are triggered\&.
504 .sp
505 Added in version 218\&.
506 .RE
507 .PP
508 \fB\-b\fR, \fB\-\-parent\-match=\fR\fB\fISYSPATH\fR\fR
509 .RS 4
510 Trigger events for all children of a given device\&. When this option is specified more than once, then each matching result is ORed, that is, all children of each specified device are triggered\&.
511 .RE
512 .PP
513 \fB\-\-initialized\-match\fR, \fB\-\-initialized\-nomatch\fR
514 .RS 4
515 When
516 \fB\-\-initialized\-match\fR
517 is specified, trigger events for devices that are already initialized by
518 \fBsystemd\-udevd\fR, and skip devices that are not initialized yet\&.
519 .sp
520 When
521 \fB\-\-initialized\-nomatch\fR
522 is specified, trigger events for devices that are not initialized by
523 \fBsystemd\-udevd\fR
524 yet, and skip devices that are already initialized\&.
525 .sp
526 Typically, it is essential that applications which intend to use such a match, make sure a suitable udev rule is installed that sets at least one property on devices that shall be matched\&. See also Initialized Devices section below for more details\&.
527 .if n \{\
528 .sp
529 .\}
530 .RS 4
531 .it 1 an-trap
532 .nr an-no-space-flag 1
533 .nr an-break-flag 1
534 .br
535 .ps +1
536 \fBWarning\fR
537 .ps -1
538 .br
539 \fB\-\-initialized\-nomatch\fR
540 can potentially save a significant amount of time compared to re\-triggering all devices in the system and e\&.g\&. can be used to optimize boot time\&. However, this is not safe to be used in a boot sequence in general\&. Especially, when udev rules for a device depend on its parent devices (e\&.g\&.
541 "ATTRS"
542 or
543 "IMPORT{parent}"
544 keys, see
545 \fBudev\fR(7)
546 for more details), the final state of the device becomes easily unstable with this option\&.
547 .sp .5v
548 .RE
549 Added in version 251\&.
550 .RE
551 .PP
552 \fB\-w\fR, \fB\-\-settle\fR
553 .RS 4
554 Apart from triggering events, also waits for those events to finish\&. Note that this is different from calling
555 \fBudevadm settle\fR\&.
556 \fBudevadm settle\fR
557 waits for all events to finish\&. This option only waits for events triggered by the same command to finish\&.
558 .sp
559 Added in version 238\&.
560 .RE
561 .PP
562 \fB\-\-uuid\fR
563 .RS 4
564 Trigger the synthetic device events, and associate a randomized UUID with each\&. These UUIDs are printed to standard output, one line for each event\&. These UUIDs are included in the uevent environment block (in the
565 "SYNTH_UUID="
566 property) and may be used to track delivery of the generated events\&.
567 .sp
568 Added in version 249\&.
569 .RE
570 .PP
571 \fB\-\-wait\-daemon[=\fR\fB\fISECONDS\fR\fR\fB]\fR
572 .RS 4
573 Before triggering uevents, wait for systemd\-udevd daemon to be initialized\&. Optionally takes timeout value\&. Default timeout is 5 seconds\&. This is equivalent to invoking
574 \fBudevadm control \-\-ping\fR
575 before
576 \fBudevadm trigger\fR\&.
577 .sp
578 Added in version 241\&.
579 .RE
580 .PP
581 \fB\-h\fR, \fB\-\-help\fR
582 .RS 4
583 Print a short help text and exit\&.
584 .RE
585 .PP
586 In addition, optional positional arguments can be used to specify device names or sys paths\&. They must start with
587 /dev/
588 or
589 /sys/
590 respectively\&.
591 .SS "udevadm settle [\fIoptions\fR]"
592 .PP
593 Watches the udev event queue, and exits if all current events are handled\&.
594 .PP
595 \fB\-t\fR, \fB\-\-timeout=\fR\fB\fISECONDS\fR\fR
596 .RS 4
597 Maximum number of seconds to wait for the event queue to become empty\&. The default value is 120 seconds\&. A value of 0 will check if the queue is empty and always return immediately\&. A non\-zero value will return an exit code of 0 if queue became empty before timeout was reached, non\-zero otherwise\&.
598 .RE
599 .PP
600 \fB\-E\fR, \fB\-\-exit\-if\-exists=\fR\fB\fIFILE\fR\fR
601 .RS 4
602 Stop waiting if file exists\&.
603 .RE
604 .PP
605 \fB\-h\fR, \fB\-\-help\fR
606 .RS 4
607 Print a short help text and exit\&.
608 .RE
609 .PP
610 See
611 \fBsystemd-udev-settle.service\fR(8)
612 for more information\&.
613 .SS "udevadm control \fIoption\fR"
614 .PP
615 Modify the internal state of the running udev daemon\&.
616 .PP
617 \fB\-e\fR, \fB\-\-exit\fR
618 .RS 4
619 Signal and wait for systemd\-udevd to exit\&. No option except for
620 \fB\-\-timeout\fR
621 can be specified after this option\&. Note that
622 systemd\-udevd\&.service
623 contains
624 \fBRestart=always\fR
625 and so as a result, this option restarts systemd\-udevd\&. If you want to stop
626 systemd\-udevd\&.service, please use the following:
627 .sp
628 .if n \{\
629 .RS 4
630 .\}
631 .nf
632 systemctl stop systemd\-udevd\-control\&.socket systemd\-udevd\-kernel\&.socket systemd\-udevd\&.service
633 .fi
634 .if n \{\
635 .RE
636 .\}
637 .sp
638 .RE
639 .PP
640 \fB\-l\fR, \fB\-\-log\-level=\fR\fB\fIvalue\fR\fR
641 .RS 4
642 Set the internal log level of
643 systemd\-udevd\&. Valid values are the numerical syslog priorities or their textual representations:
644 \fBemerg\fR,
645 \fBalert\fR,
646 \fBcrit\fR,
647 \fBerr\fR,
648 \fBwarning\fR,
649 \fBnotice\fR,
650 \fBinfo\fR, and
651 \fBdebug\fR\&.
652 .RE
653 .PP
654 \fB\-s\fR, \fB\-\-stop\-exec\-queue\fR
655 .RS 4
656 Signal systemd\-udevd to stop executing new events\&. Incoming events will be queued\&.
657 .RE
658 .PP
659 \fB\-S\fR, \fB\-\-start\-exec\-queue\fR
660 .RS 4
661 Signal systemd\-udevd to enable the execution of events\&.
662 .RE
663 .PP
664 \fB\-R\fR, \fB\-\-reload\fR
665 .RS 4
666 Signal systemd\-udevd to reload the rules files and other databases like the kernel module index\&. Reloading rules and databases does not apply any changes to already existing devices; the new configuration will only be applied to new events\&.
667 .RE
668 .PP
669 \fB\-p\fR, \fB\-\-property=\fR\fB\fIKEY\fR\fR\fB=\fR\fB\fIvalue\fR\fR
670 .RS 4
671 Set a global property for all events\&.
672 .RE
673 .PP
674 \fB\-m\fR, \fB\-\-children\-max=\fR\fB\fIvalue\fR\fR
675 .RS 4
676 Set the maximum number of events, systemd\-udevd will handle at the same time\&. When 0 is specified, then the maximum is determined based on the system resources\&.
677 .RE
678 .PP
679 \fB\-\-ping\fR
680 .RS 4
681 Send a ping message to systemd\-udevd and wait for the reply\&. This may be useful to check that systemd\-udevd daemon is running\&.
682 .sp
683 Added in version 241\&.
684 .RE
685 .PP
686 \fB\-t\fR, \fB\-\-timeout=\fR\fB\fIseconds\fR\fR
687 .RS 4
688 The maximum number of seconds to wait for a reply from systemd\-udevd\&.
689 .RE
690 .PP
691 \fB\-\-load\-credentials\fR
692 .RS 4
693 When specified, the following credentials are used when passed in:
694 .PP
695 \fIudev\&.conf\&.*\fR
696 .RS 4
697 These credentials should contain valid
698 \fBudev.conf\fR(5)
699 configuration data\&. From each matching credential a separate file is created\&. Example: a passed credential
700 udev\&.conf\&.50\-foobar
701 will be copied into a configuration file
702 /run/udev/udev\&.conf\&.d/50\-foobar\&.conf\&.
703 .sp
704 Added in version 256\&.
705 .RE
706 .PP
707 \fIudev\&.rules\&.*\fR
708 .RS 4
709 These credentials should contain valid
710 \fBudev\fR(7)
711 rules\&. From each matching credential a separate file is created\&. Example: a passed credential
712 udev\&.rules\&.50\-foobar
713 will be copied into a configuration file
714 /run/udev/rules\&.d/50\-foobar\&.rules\&.
715 .sp
716 Added in version 256\&.
717 .RE
718 .sp
719 Note, this
720 \fIdoes not\fR
721 imply
722 \fB\-\-reload\fR
723 option\&. So, if
724 \fBsystemd\-udevd\fR
725 is already running, please consider to also specify
726 \fB\-reload\fR
727 to make the copied udev rules files used by
728 \fBsystemd\-udevd\fR\&.
729 .sp
730 Added in version 256\&.
731 .RE
732 .PP
733 \fB\-h\fR, \fB\-\-help\fR
734 .RS 4
735 Print a short help text and exit\&.
736 .RE
737 .SS "udevadm monitor [\fIoptions\fR]"
738 .PP
739 Listens to the kernel uevents and events sent out by a udev rule and prints the devpath of the event to the console\&. It can be used to analyze the event timing, by comparing the timestamps of the kernel uevent and the udev event\&.
740 .PP
741 \fB\-k\fR, \fB\-\-kernel\fR
742 .RS 4
743 Print the kernel uevents\&.
744 .RE
745 .PP
746 \fB\-u\fR, \fB\-\-udev\fR
747 .RS 4
748 Print the udev event after the rule processing\&.
749 .RE
750 .PP
751 \fB\-p\fR, \fB\-\-property\fR
752 .RS 4
753 Also print the properties of the event\&.
754 .RE
755 .PP
756 \fB\-s\fR, \fB\-\-subsystem\-match=\fR\fB\fIstring[/string]\fR\fR
757 .RS 4
758 Filter kernel uevents and udev events by subsystem[/devtype]\&. Only events with a matching subsystem value will pass\&. When this option is specified more than once, then each matching result is ORed, that is, all devices in the specified subsystems are monitored\&.
759 .RE
760 .PP
761 \fB\-t\fR, \fB\-\-tag\-match=\fR\fB\fIstring\fR\fR
762 .RS 4
763 Filter udev events by tag\&. Only udev events with a given tag attached will pass\&. When this option is specified more than once, then each matching result is ORed, that is, devices which have one of the specified tags are monitored\&.
764 .RE
765 .PP
766 \fB\-h\fR, \fB\-\-help\fR
767 .RS 4
768 Print a short help text and exit\&.
769 .RE
770 .SS "udevadm test [\fIoptions\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]"
771 .PP
772 Simulate a udev event run for the given device, and print debug output\&.
773 .PP
774 \fB\-a\fR, \fB\-\-action=\fR\fB\fIACTION\fR\fR
775 .RS 4
776 Type of event to be simulated\&. Possible actions are
777 "add",
778 "remove",
779 "change",
780 "move",
781 "online",
782 "offline",
783 "bind", and
784 "unbind"\&. Also, the special value
785 "help"
786 can be used to list the possible actions\&. The default value is
787 "add"\&.
788 .RE
789 .PP
790 \fB\-N\fR, \fB\-\-resolve\-names=\fR\fB\fBearly\fR\fR\fB|\fR\fB\fBlate\fR\fR\fB|\fR\fB\fBnever\fR\fR
791 .RS 4
792 Specify when udevadm should resolve names of users and groups\&. When set to
793 \fBearly\fR
794 (the default), names will be resolved when the rules are parsed\&. When set to
795 \fBlate\fR, names will be resolved for every event\&. When set to
796 \fBnever\fR, names will never be resolved and all devices will be owned by root\&.
797 .sp
798 Added in version 209\&.
799 .RE
800 .PP
801 \fB\-h\fR, \fB\-\-help\fR
802 .RS 4
803 Print a short help text and exit\&.
804 .RE
805 .SS "udevadm test\-builtin [\fIoptions\fR] \fIcommand\fR [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]"
806 .PP
807 Run a built\-in command
808 \fICOMMAND\fR
809 for device
810 \fIDEVPATH\fR, and print debug output\&.
811 .PP
812 \fB\-a\fR, \fB\-\-action=\fR\fB\fIACTION\fR\fR
813 .RS 4
814 Type of event to be simulated\&. Possible actions are
815 "add",
816 "remove",
817 "change",
818 "move",
819 "online",
820 "offline",
821 "bind", and
822 "unbind"\&. Also, the special value
823 "help"
824 can be used to list the possible actions\&. The default value is
825 "add"\&.
826 .sp
827 Added in version 250\&.
828 .RE
829 .PP
830 \fB\-h\fR, \fB\-\-help\fR
831 .RS 4
832 Print a short help text and exit\&.
833 .RE
834 .PP
835 \fB\-\-version\fR
836 .RS 4
837 Print a short version string and exit\&.
838 .RE
839 .SS "udevadm verify [\fIoptions\fR] [\fIfile\fR] \&..."
840 .PP
841 Verify syntactic, semantic, and stylistic correctness of udev rules files\&.
842 .PP
843 Positional arguments could be used to specify one or more files to check\&. If no files are specified, the udev rules are read from the files located in the same udev/rules\&.d directories that are processed by the udev daemon\&.
844 .PP
845 The exit status is
846 \fB0\fR
847 if all specified udev rules files are syntactically, semantically, and stylistically correct, and a non\-zero error code otherwise\&.
848 .PP
849 \fB\-N\fR, \fB\-\-resolve\-names=\fR\fB\fBearly\fR\fR\fB|\fR\fB\fBnever\fR\fR
850 .RS 4
851 Specify when udevadm should resolve names of users and groups\&. When set to
852 \fBearly\fR
853 (the default), names will be resolved when the rules are parsed\&. When set to
854 \fBnever\fR, names will never be resolved\&.
855 .sp
856 Added in version 254\&.
857 .RE
858 .PP
859 \fB\-\-root=\fR\fB\fIPATH\fR\fR
860 .RS 4
861 When looking for udev rules files located in udev/rules\&.d directories, operate on files underneath the specified root path
862 \fIPATH\fR\&.
863 .sp
864 Added in version 254\&.
865 .RE
866 .PP
867 \fB\-\-no\-summary\fR
868 .RS 4
869 Do not show summary\&.
870 .sp
871 Added in version 254\&.
872 .RE
873 .PP
874 \fB\-\-no\-style\fR
875 .RS 4
876 Ignore style issues\&. When specified, even if style issues are found in udev rules files, the exit status is
877 \fB0\fR
878 if no syntactic or semantic errors are found\&.
879 .sp
880 Added in version 254\&.
881 .RE
882 .PP
883 \fB\-h\fR, \fB\-\-help\fR
884 .RS 4
885 Print a short help text and exit\&.
886 .RE
887 .SS "udevadm wait [\fIoptions\fR] [\fIdevice|syspath\fR] \&..."
888 .PP
889 Wait for devices or device symlinks being created and initialized by
890 \fBsystemd\-udevd\fR\&. Each device path must start with
891 "/dev/"
892 or
893 "/sys/", e\&.g\&.
894 "/dev/sda",
895 "/dev/disk/by\-path/pci\-0000:3c:00\&.0\-nvme\-1\-part1",
896 "/sys/devices/pci0000:00/0000:00:1f\&.6/net/eth0", or
897 "/sys/class/net/eth0"\&. This can take multiple devices\&. This may be useful for waiting for devices being processed by
898 \fBsystemd\-udevd\fR
899 after e\&.g\&. partitioning or formatting the devices\&.
900 .PP
901 \fB\-t\fR, \fB\-\-timeout=\fR\fB\fISECONDS\fR\fR
902 .RS 4
903 Maximum number of seconds to wait for the specified devices or device symlinks being created, initialized, or removed\&. The default value is
904 "infinity"\&.
905 .sp
906 Added in version 251\&.
907 .RE
908 .PP
909 \fB\-\-initialized=\fR\fB\fIBOOL\fR\fR
910 .RS 4
911 Check if
912 \fBsystemd\-udevd\fR
913 initialized devices\&. Defaults to true\&. When false, the command only checks if the specified devices exist\&. Set false to this setting if there is no udev rules for the specified devices, as the devices will never be considered as initialized in that case\&. See Initialized Devices section below for more details\&.
914 .sp
915 Added in version 251\&.
916 .RE
917 .PP
918 \fB\-\-removed\fR
919 .RS 4
920 When specified, the command wait for devices being removed instead of created or initialized\&. If this is specified,
921 \fB\-\-initialized=\fR
922 will be ignored\&.
923 .sp
924 Added in version 251\&.
925 .RE
926 .PP
927 \fB\-\-settle\fR
928 .RS 4
929 When specified, also watches the udev event queue, and wait for all queued events being processed by
930 \fBsystemd\-udevd\fR\&.
931 .sp
932 Added in version 251\&.
933 .RE
934 .PP
935 \fB\-h\fR, \fB\-\-help\fR
936 .RS 4
937 Print a short help text and exit\&.
938 .RE
939 .SS "udevadm lock [\fIoptions\fR] [\fIcommand\fR] \&..."
940 .PP
941 \fBudevadm lock\fR
942 takes an (advisory) exclusive lock on a block device (or all specified devices), as per
943 \m[blue]\fBLocking Block Device Access\fR\m[]\&\s-2\u[2]\d\s+2
944 and invokes a program with the locks taken\&. When the invoked program exits the locks are automatically released and its return value is propagated as exit code of
945 \fBudevadm lock\fR\&.
946 .PP
947 This tool is in particular useful to ensure that
948 \fBsystemd-udevd.service\fR(8)
949 does not probe a block device while changes are made to it, for example partitions created or file systems formatted\&. Note that many tools that interface with block devices natively support taking relevant locks, see for example
950 \fBsfdisk\fR(8)\*(Aqs
951 \fB\-\-lock\fR
952 switch\&.
953 .PP
954 The command expects at least one block device specified via
955 \fB\-\-device=\fR
956 or
957 \fB\-\-backing=\fR, and a command line to execute as arguments\&.
958 .PP
959 \fB\-\-device=\fR\fB\fIDEVICE\fR\fR, \fB\-d \fR\fB\fIDEVICE\fR\fR
960 .RS 4
961 Takes a path to a device node of the device to lock\&. This switch may be used multiple times (and in combination with
962 \fB\-\-backing=\fR) in order to lock multiple devices\&. If a partition block device node is specified the containing "whole" block device is automatically determined and used for the lock, as per the specification\&. If multiple devices are specified, they are deduplicated, sorted by the major/minor of their device nodes and then locked in order\&.
963 .sp
964 This switch must be used at least once, to specify at least one device to lock\&. (Alternatively, use
965 \fB\-\-backing=\fR, see below\&.)
966 .sp
967 Added in version 251\&.
968 .RE
969 .PP
970 \fB\-\-backing=\fR\fB\fIPATH\fR\fR, \fB\-b \fR\fB\fIPATH\fR\fR
971 .RS 4
972 If a path to a device node is specified, identical to
973 \fB\-\-device=\fR\&. However, this switch alternatively accepts a path to a regular file or directory, in which case the block device of the file system the file/directory resides on is automatically determined and used as if it was specified with
974 \fB\-\-device=\fR\&.
975 .sp
976 Added in version 251\&.
977 .RE
978 .PP
979 \fB\-\-timeout=\fR\fB\fISECS\fR\fR, \fB\-t \fR\fB\fISECS\fR\fR
980 .RS 4
981 Specifies how long to wait at most until all locks can be taken\&. Takes a value in seconds, or in the usual supported time units, see
982 \fBsystemd.time\fR(7)\&. If specified as zero the lock is attempted and if not successful the invocation will immediately fail\&. If passed as
983 "infinity"
984 (the default) the invocation will wait indefinitely until the lock can be acquired\&. If the lock cannot be taken in the specified time the specified command will not be executed and the invocation will fail\&.
985 .sp
986 Added in version 251\&.
987 .RE
988 .PP
989 \fB\-\-print\fR, \fB\-p\fR
990 .RS 4
991 Instead of locking the specified devices and executing a command, just print the device paths that would be locked, and execute no command\&. This command is useful to determine the "whole" block device in case a partition block device is specified\&. The devices will be sorted by their device node major number as primary ordering key and the minor number as secondary ordering key (i\&.e\&. they are shown in the order they\*(Aqd be locked)\&. Note that the number of lines printed here can be less than the number of
992 \fB\-\-device=\fR
993 and
994 \fB\-\-backing=\fR
995 switches specified in case these resolve to the same "whole" devices\&.
996 .sp
997 Added in version 251\&.
998 .RE
999 .PP
1000 \fB\-h\fR, \fB\-\-help\fR
1001 .RS 4
1002 Print a short help text and exit\&.
1003 .RE
1004 .SH "INITIALIZED DEVICES"
1005 .PP
1006 Initialized devices are those for which at least one udev rule already completed execution \(en for any action but
1007 "remove"
1008 \(em that set a property or other device setting (and thus has an entry in the udev device database)\&. Devices are no longer considered initialized if a
1009 "remove"
1010 action is seen for them (which removes their entry in the udev device database)\&. Note that devices that have no udev rules are never considered initialized, but might still be announced via the sd\-device API (or similar)\&.
1011 .SH "EXAMPLE"
1012 .PP
1013 \fBExample\ \&1.\ \&Format a File System\fR
1014 .PP
1015 Take a lock on the backing block device while creating a file system, to ensure that
1016 \fBsystemd\-udevd\fR
1017 doesn\*(Aqt probe or announce the new superblock before it is comprehensively written:
1018 .sp
1019 .if n \{\
1020 .RS 4
1021 .\}
1022 .nf
1023 # udevadm lock \-\-device=/dev/sda1 mkfs\&.ext4 /dev/sda1
1024 .fi
1025 .if n \{\
1026 .RE
1027 .\}
1028 .PP
1029 \fBExample\ \&2.\ \&Format a RAID File System\fR
1030 .PP
1031 Similar, but take locks on multiple devices at once:
1032 .sp
1033 .if n \{\
1034 .RS 4
1035 .\}
1036 .nf
1037 # udevadm lock \-\-device=/dev/sda1 \-\-device=/dev/sdb1 mkfs\&.btrfs /dev/sda1 /dev/sdb1
1038 .fi
1039 .if n \{\
1040 .RE
1041 .\}
1042 .PP
1043 \fBExample\ \&3.\ \&Copy in a File System\fR
1044 .PP
1045 Take a lock on the backing block device while copying in a prepared file system image, to ensure that
1046 \fBsystemd\-udevd\fR
1047 doesn\*(Aqt probe or announce the new superblock before it is fully written:
1048 .sp
1049 .if n \{\
1050 .RS 4
1051 .\}
1052 .nf
1053 # udevadm lock \-d /dev/sda1 dd if=fs\&.raw of=/dev/sda1
1054 .fi
1055 .if n \{\
1056 .RE
1057 .\}
1058 .SH "SEE ALSO"
1059 .PP
1060 \fBudev\fR(7), \fBsystemd-udevd.service\fR(8)
1061 .SH "NOTES"
1062 .IP " 1." 4
1063 jq
1064 .RS 4
1065 \%https://jqlang.github.io/jq/manual/
1066 .RE
1067 .IP " 2." 4
1068 Locking Block Device Access
1069 .RS 4
1070 \%https://systemd.io/BLOCK_DEVICE_LOCKING
1071 .RE