]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/udevadm.xml
man: document that the passive units cannot be pulled in mnaully
[thirdparty/systemd.git] / man / udevadm.xml
CommitLineData
225cb03b 1<?xml version='1.0'?>
63749b1a
KS
2<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
3<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
225cb03b
KS
4 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5
63749b1a
KS
6<refentry id="udevadm">
7 <refentryinfo>
225cb03b 8 <title>udevadm</title>
d3a2386d
KS
9 <productname>systemd</productname>
10 <authorgroup>
11 <author>
12 <contrib>Developer</contrib>
13 <firstname>Kay</firstname>
14 <surname>Sievers</surname>
15 <email>kay@vrfy.org</email>
16 </author>
17 </authorgroup>
63749b1a 18 </refentryinfo>
225cb03b 19
63749b1a
KS
20 <refmeta>
21 <refentrytitle>udevadm</refentrytitle>
22 <manvolnum>8</manvolnum>
23 <refmiscinfo class="version"></refmiscinfo>
24 </refmeta>
225cb03b 25
63749b1a
KS
26 <refnamediv>
27 <refname>udevadm</refname><refpurpose>udev management tool</refpurpose>
28 </refnamediv>
225cb03b 29
63749b1a
KS
30 <refsynopsisdiv>
31 <cmdsynopsis>
32 <command>udevadm</command>
33 <arg><option>--debug</option></arg>
34 <arg><option>--version</option></arg>
35 <arg><option>--help</option></arg>
36 </cmdsynopsis>
37 <cmdsynopsis>
38 <command>udevadm info <replaceable>options</replaceable></command>
39 </cmdsynopsis>
40 <cmdsynopsis>
41 <command>udevadm trigger <optional>options</optional></command>
42 </cmdsynopsis>
43 <cmdsynopsis>
44 <command>udevadm settle <optional>options</optional></command>
45 </cmdsynopsis>
46 <cmdsynopsis>
47 <command>udevadm control <replaceable>command</replaceable></command>
48 </cmdsynopsis>
49 <cmdsynopsis>
50 <command>udevadm monitor <optional>options</optional></command>
51 </cmdsynopsis>
1ada30ac
KS
52 <cmdsynopsis>
53 <command>udevadm hwdb <optional>options</optional></command>
54 </cmdsynopsis>
63749b1a
KS
55 <cmdsynopsis>
56 <command>udevadm test <optional>options</optional> <replaceable>devpath</replaceable></command>
57 </cmdsynopsis>
d7867b31
KS
58 <cmdsynopsis>
59 <command>udevadm test-builtin <optional>options</optional> <replaceable>command</replaceable> <replaceable>devpath</replaceable></command>
60 </cmdsynopsis>
63749b1a 61 </refsynopsisdiv>
225cb03b 62
63749b1a
KS
63 <refsect1><title>Description</title>
64 <para>udevadm expects a command and command specific options. It
65 controls the runtime behavior of udev, requests kernel events,
66 manages the event queue, and provides simple debugging mechanisms.</para>
67 </refsect1>
225cb03b 68
63749b1a
KS
69 <refsect1><title>OPTIONS</title>
70 <variablelist>
71 <varlistentry>
72 <term><option>--debug</option></term>
73 <listitem>
74 <para>Print debug messages to stderr.</para>
75 </listitem>
76 </varlistentry>
77 <varlistentry>
78 <term><option>--version</option></term>
79 <listitem>
80 <para>Print version number.</para>
81 </listitem>
82 </varlistentry>
83 <varlistentry>
84 <term><option>--help</option></term>
85 <listitem>
86 <para>Print help text.</para>
87 </listitem>
88 </varlistentry>
89 </variablelist>
225cb03b 90
63749b1a
KS
91 <refsect2><title>udevadm info <replaceable>options</replaceable></title>
92 <para>Queries the udev database for device information
93 stored in the udev database. It can also query the properties
94 of a device from its sysfs representation to help creating udev
95 rules that match this device.</para>
96 <variablelist>
97 <varlistentry>
98 <term><option>--query=<replaceable>type</replaceable></option></term>
99 <listitem>
100 <para>Query the database for specified type of device data. It needs the
101 <option>--path</option> or <option>--name</option> to identify the specified
102 device. Valid queries are:
103 <command>name</command>, <command>symlink</command>, <command>path</command>,
104 <command>property</command>, <command>all</command>.</para>
105 </listitem>
106 </varlistentry>
107 <varlistentry>
108 <term><option>--path=<replaceable>devpath</replaceable></option></term>
109 <listitem>
110 <para>The devpath of the device to query.</para>
111 </listitem>
112 </varlistentry>
113 <varlistentry>
114 <term><option>--name=<replaceable>file</replaceable></option></term>
115 <listitem>
116 <para>The name of the device node or a symlink to query</para>
117 </listitem>
118 </varlistentry>
119 <varlistentry>
120 <term><option>--root</option></term>
121 <listitem>
4f5d327a
KS
122 <para>Print absolute paths in <command>name</command> or <command>symlink</command>
123 query.</para>
4ec9c3e7
KS
124 </listitem>
125 </varlistentry>
63749b1a
KS
126 <varlistentry>
127 <term><option>--attribute-walk</option></term>
128 <listitem>
129 <para>Print all sysfs properties of the specified device that can be used
130 in udev rules to match the specified device. It prints all devices
131 along the chain, up to the root of sysfs that can be used in udev rules.</para>
132 </listitem>
133 </varlistentry>
dc1791a9
KS
134 <varlistentry>
135 <term><option>--export</option></term>
136 <listitem>
137 <para>Print output as key/value pairs. Values are enclosed in single quotes.</para>
138 </listitem>
139 </varlistentry>
140 <varlistentry>
141 <term><option>--export-prefix=<replaceable>name</replaceable></option></term>
142 <listitem>
143 <para>Add a prefix to the key name of exported values.</para>
144 </listitem>
145 </varlistentry>
63749b1a
KS
146 <varlistentry>
147 <term><option>--device-id-of-file=<replaceable>file</replaceable></option></term>
148 <listitem>
149 <para>Print major/minor numbers of the underlying device, where the file
150 lives on.</para>
151 </listitem>
152 </varlistentry>
153 <varlistentry>
154 <term><option>--export-db</option></term>
155 <listitem>
156 <para>Export the content of the udev database.</para>
157 </listitem>
158 </varlistentry>
9ead6627
KS
159 <varlistentry>
160 <term><option>--cleanup-db</option></term>
161 <listitem>
162 <para>Cleanup the udev database.</para>
163 </listitem>
164 </varlistentry>
63749b1a
KS
165 <varlistentry>
166 <term><option>--version</option></term>
167 <listitem>
168 <para>Print version.</para>
169 </listitem>
170 </varlistentry>
171 <varlistentry>
172 <term><option>--help</option></term>
173 <listitem>
174 <para>Print help text.</para>
175 </listitem>
176 </varlistentry>
177 </variablelist>
178 </refsect2>
225cb03b 179
63749b1a
KS
180 <refsect2><title>udevadm trigger <optional>options</optional></title>
181 <para>Request device events from the kernel. Primarily used to replay events at system coldplug time.</para>
182 <variablelist>
183 <varlistentry>
184 <term><option>--verbose</option></term>
185 <listitem>
186 <para>Print the list of devices which will be triggered.</para>
187 </listitem>
188 </varlistentry>
189 <varlistentry>
190 <term><option>--dry-run</option></term>
191 <listitem>
192 <para>Do not actually trigger the event.</para>
193 </listitem>
194 </varlistentry>
195 <varlistentry>
196 <term><option>--type=<replaceable>type</replaceable></option></term>
197 <listitem>
198 <para>Trigger a specific type of devices. Valid types are:
864fde8a 199 <command>devices</command>, <command>subsystems</command>.
63749b1a
KS
200 The default value is <command>devices</command>.</para>
201 </listitem>
202 </varlistentry>
203 <varlistentry>
204 <term><option>--action=<replaceable>action</replaceable></option></term>
205 <listitem>
206 <para>Type of event to be triggered. The default value is <command>change</command>.</para>
207 </listitem>
208 </varlistentry>
209 <varlistentry>
210 <term><option>--subsystem-match=<replaceable>subsystem</replaceable></option></term>
211 <listitem>
212 <para>Trigger events for devices which belong to a matching subsystem. This option
213 can be specified multiple times and supports shell style pattern matching.</para>
214 </listitem>
215 </varlistentry>
216 <varlistentry>
217 <term><option>--subsystem-nomatch=<replaceable>subsystem</replaceable></option></term>
218 <listitem>
219 <para>Do not trigger events for devices which belong to a matching subsystem. This option
220 can be specified multiple times and supports shell style pattern matching.</para>
221 </listitem>
222 </varlistentry>
223 <varlistentry>
224 <term><option>--attr-match=<replaceable>attribute</replaceable>=<replaceable>value</replaceable></option></term>
225 <listitem>
226 <para>Trigger events for devices with a matching sysfs attribute. If a value is specified
227 along with the attribute name, the content of the attribute is matched against the given
228 value using shell style pattern matching. If no value is specified, the existence of the
229 sysfs attribute is checked. This option can be specified multiple times.</para>
230 </listitem>
231 </varlistentry>
232 <varlistentry>
233 <term><option>--attr-nomatch=<replaceable>attribute</replaceable>=<replaceable>value</replaceable></option></term>
234 <listitem>
235 <para>Do not trigger events for devices with a matching sysfs attribute. If a value is
236 specified along with the attribute name, the content of the attribute is matched against
237 the given value using shell style pattern matching. If no value is specified, the existence
238 of the sysfs attribute is checked. This option can be specified multiple times.</para>
239 </listitem>
240 </varlistentry>
241 <varlistentry>
242 <term><option>--property-match=<replaceable>property</replaceable>=<replaceable>value</replaceable></option></term>
243 <listitem>
244 <para>Trigger events for devices with a matching property value. This option can be
245 specified multiple times and supports shell style pattern matching.</para>
246 </listitem>
247 </varlistentry>
248 <varlistentry>
249 <term><option>--tag-match=<replaceable>property</replaceable></option></term>
250 <listitem>
251 <para>Trigger events for devices with a matching tag. This option can be
252 specified multiple times.</para>
253 </listitem>
254 </varlistentry>
255 <varlistentry>
256 <term><option>--sysname-match=<replaceable>name</replaceable></option></term>
257 <listitem>
258 <para>Trigger events for devices with a matching sys device name. This option can be
259 specified multiple times and supports shell style pattern matching.</para>
260 </listitem>
261 </varlistentry>
b05211fa
KS
262 <varlistentry>
263 <term><option>--parent-match=<replaceable>syspath</replaceable></option></term>
264 <listitem>
265 <para>Trigger events for all children of a given device.</para>
266 </listitem>
267 </varlistentry>
63749b1a
KS
268 </variablelist>
269 </refsect2>
225cb03b 270
63749b1a
KS
271 <refsect2><title>udevadm settle <optional>options</optional></title>
272 <para>Watches the udev event queue, and exits if all current events are handled.</para>
273 <variablelist>
274 <varlistentry>
275 <term><option>--timeout=<replaceable>seconds</replaceable></option></term>
276 <listitem>
277 <para>Maximum number of seconds to wait for the event queue to become empty.
d2f4a346 278 The default value is 120 seconds. A value of 0 will check if the queue is empty
63749b1a
KS
279 and always return immediately.</para>
280 </listitem>
281 </varlistentry>
282 <varlistentry>
283 <term><option>--seq-start=<replaceable>seqnum</replaceable></option></term>
284 <listitem>
285 <para>Wait only for events after the given sequence number.</para>
286 </listitem>
287 </varlistentry>
288 <varlistentry>
289 <term><option>--seq-end=<replaceable>seqnum</replaceable></option></term>
290 <listitem>
291 <para>Wait only for events before the given sequence number.</para>
292 </listitem>
293 </varlistentry>
294 <varlistentry>
295 <term><option>--exit-if-exists=<replaceable>file</replaceable></option></term>
296 <listitem>
297 <para>Stop waiting if file exists.</para>
298 </listitem>
299 </varlistentry>
300 <varlistentry>
301 <term><option>--quiet</option></term>
302 <listitem>
303 <para>Do not print any output, like the remaining queue entries when reaching the timeout.</para>
304 </listitem>
305 </varlistentry>
306 <varlistentry>
307 <term><option>--help</option></term>
308 <listitem>
309 <para>Print help text.</para>
310 </listitem>
311 </varlistentry>
312 </variablelist>
313 </refsect2>
225cb03b 314
63749b1a
KS
315 <refsect2><title>udevadm control <replaceable>command</replaceable></title>
316 <para>Modify the internal state of the running udev daemon.</para>
317 <variablelist>
ff2c503d
KS
318 <varlistentry>
319 <term><option>--exit</option></term>
320 <listitem>
f13b388f 321 <para>Signal and wait for systemd-udevd to exit.</para>
ff2c503d
KS
322 </listitem>
323 </varlistentry>
63749b1a
KS
324 <varlistentry>
325 <term><option>--log-priority=<replaceable>value</replaceable></option></term>
326 <listitem>
f13b388f 327 <para>Set the internal log level of systemd-udevd. Valid values are the numerical
63749b1a
KS
328 syslog priorities or their textual representations: <option>err</option>,
329 <option>info</option> and <option>debug</option>.</para>
330 </listitem>
331 </varlistentry>
332 <varlistentry>
333 <term><option>--stop-exec-queue</option></term>
334 <listitem>
f13b388f 335 <para>Signal systemd-udevd to stop executing new events. Incoming events
63749b1a
KS
336 will be queued.</para>
337 </listitem>
338 </varlistentry>
339 <varlistentry>
340 <term><option>--start-exec-queue</option></term>
341 <listitem>
f13b388f 342 <para>Signal systemd-udevd to enable the execution of events.</para>
63749b1a
KS
343 </listitem>
344 </varlistentry>
345 <varlistentry>
7c85d636 346 <term><option>--reload</option></term>
63749b1a 347 <listitem>
f13b388f 348 <para>Signal systemd-udevd to reload the rules files and other databases like the kernel
7c85d636
KS
349 module index. Reloading rules and databases does not apply any changes to already
350 existing devices; the new configuration will only be applied to new events.</para>
63749b1a
KS
351 </listitem>
352 </varlistentry>
353 <varlistentry>
354 <term><option>--property=<replaceable>KEY</replaceable>=<replaceable>value</replaceable></option></term>
355 <listitem>
356 <para>Set a global property for all events.</para>
357 </listitem>
358 </varlistentry>
359 <varlistentry>
87d55ff6 360 <term><option>--children-max=</option><replaceable>value</replaceable></term>
63749b1a 361 <listitem>
f13b388f 362 <para>Set the maximum number of events, systemd-udevd will handle at the
63749b1a
KS
363 same time.</para>
364 </listitem>
365 </varlistentry>
ff2c503d
KS
366 <varlistentry>
367 <term><option>--timeout=</option><replaceable>seconds</replaceable></term>
368 <listitem>
7e505069 369 <para>The maximum number of seconds to wait for a reply from systemd-udevd.</para>
ff2c503d
KS
370 </listitem>
371 </varlistentry>
63749b1a
KS
372 <varlistentry>
373 <term><option>--help</option></term>
374 <listitem>
375 <para>Print help text.</para>
376 </listitem>
377 </varlistentry>
378 </variablelist>
379 </refsect2>
225cb03b 380
63749b1a
KS
381 <refsect2><title>udevadm monitor <optional>options</optional></title>
382 <para>Listens to the kernel uevents and events sent out by a udev rule
383 and prints the devpath of the event to the console. It can be used to analyze the
384 event timing, by comparing the timestamps of the kernel uevent and the udev event.
385 </para>
386 <variablelist>
387 <varlistentry>
388 <term><option>--kernel</option></term>
389 <listitem>
390 <para>Print the kernel uevents.</para>
391 </listitem>
392 </varlistentry>
393 <varlistentry>
394 <term><option>--udev</option></term>
395 <listitem>
396 <para>Print the udev event after the rule processing.</para>
397 </listitem>
398 </varlistentry>
399 <varlistentry>
400 <term><option>--property</option></term>
401 <listitem>
402 <para>Also print the properties of the event.</para>
403 </listitem>
404 </varlistentry>
405 <varlistentry>
406 <term><option>--subsystem-match=<replaceable>string[/string]</replaceable></option></term>
407 <listitem>
408 <para>Filter events by subsystem[/devtype]. Only udev events with a matching subsystem value will pass.</para>
409 </listitem>
410 </varlistentry>
411 <varlistentry>
412 <term><option>--tag-match=<replaceable>string</replaceable></option></term>
413 <listitem>
414 <para>Filter events by property. Only udev events with a given tag attached will pass.</para>
415 </listitem>
416 </varlistentry>
417 <varlistentry>
418 <term><option>--help</option></term>
419 <listitem>
420 <para>Print help text.</para>
421 </listitem>
422 </varlistentry>
423 </variablelist>
424 </refsect2>
225cb03b 425
1ada30ac 426 <refsect2><title>udevadm hwdb <optional>options</optional></title>
1e1954f5 427 <para>Maintain the hardware database index in <filename>/etc/udev/hwdb.bin</filename>.</para>
1ada30ac
KS
428 <variablelist>
429 <varlistentry>
430 <term><option>--update</option></term>
431 <listitem>
04ba11b2
ED
432 <para>Compile the hardware database information located in /usr/lib/udev/hwdb.d/,
433 /etc/udev/hwdb.d/ and store it in <filename>/etc/udev/hwdb.bin</filename>. This should be done after
434 any update to the source files; it will not be called automatically. The running
1ada30ac
KS
435 udev daemon will detect a new database on its own and does not need to be
436 notified about it.</para>
437 </listitem>
438 </varlistentry>
23b72453
KS
439 <varlistentry>
440 <term><option>--test=<replaceable>string</replaceable></option></term>
441 <listitem>
442 <para>Query the database with a modalias string, and print the
443 retrieved properties.</para>
444 </listitem>
445 </varlistentry>
3e49f2ec
KS
446 <varlistentry>
447 <term><option>--root=<replaceable>string</replaceable></option></term>
448 <listitem>
449 <para>Alternative root path in the filesystem for reading and writing files.</para>
450 </listitem>
451 </varlistentry>
1ada30ac
KS
452 </variablelist>
453 </refsect2>
454
63749b1a
KS
455 <refsect2><title>udevadm test <optional>options</optional> <replaceable>devpath</replaceable></title>
456 <para>Simulate a udev event run for the given device, and print debug output.</para>
457 <variablelist>
458 <varlistentry>
459 <term><option>--action=<replaceable>string</replaceable></option></term>
460 <listitem>
461 <para>The action string.</para>
462 </listitem>
463 </varlistentry>
464 <varlistentry>
465 <term><option>--subsystem=<replaceable>string</replaceable></option></term>
466 <listitem>
467 <para>The subsystem string.</para>
468 </listitem>
469 </varlistentry>
470 <varlistentry>
471 <term><option>--help</option></term>
472 <listitem>
473 <para>Print help text.</para>
474 </listitem>
475 </varlistentry>
476 </variablelist>
477 </refsect2>
d7867b31
KS
478
479 <refsect2><title>udevadm test-builtin <optional>options</optional> <replaceable>command</replaceable> <replaceable>devpath</replaceable></title>
480 <para>Run a built-in command for the given device, and print debug output.</para>
481 <variablelist>
482 <varlistentry>
483 <term><option>--help</option></term>
484 <listitem>
485 <para>Print help text.</para>
486 </listitem>
487 </varlistentry>
488 </variablelist>
489 </refsect2>
63749b1a 490 </refsect1>
225cb03b 491
63749b1a
KS
492 <refsect1>
493 <title>See Also</title>
494 <para><citerefentry>
495 <refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum>
496 </citerefentry>
497 <citerefentry>
b79f817b 498 <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum>
63749b1a
KS
499 </citerefentry></para>
500 </refsect1>
501</refentry>