diff options
Diffstat (limited to 'upstream/archlinux/man8/udevadm.8')
| -rw-r--r-- | upstream/archlinux/man8/udevadm.8 | 994 |
1 files changed, 994 insertions, 0 deletions
diff --git a/upstream/archlinux/man8/udevadm.8 b/upstream/archlinux/man8/udevadm.8 new file mode 100644 index 00000000..234da89e --- /dev/null +++ b/upstream/archlinux/man8/udevadm.8 @@ -0,0 +1,994 @@ +'\" t +.TH "UDEVADM" "8" "" "systemd 255" "udevadm" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +udevadm \- udev management tool +.SH "SYNOPSIS" +.HP \w'\fBudevadm\fR\ 'u +\fBudevadm\fR [\fB\-\-debug\fR] [\fB\-\-version\fR] [\fB\-\-help\fR] +.HP \w'\fBudevadm\ info\ \fR\fB[options]\fR\fB\ \fR\fB[devpath]\fR\ 'u +\fBudevadm info \fR\fB[options]\fR\fB \fR\fB[devpath]\fR +.HP \w'\fBudevadm\ trigger\ \fR\fB[options]\fR\fB\ \fR\fB[devpath]\fR\ 'u +\fBudevadm trigger \fR\fB[options]\fR\fB \fR\fB[devpath]\fR +.HP \w'\fBudevadm\ settle\ \fR\fB[options]\fR\ 'u +\fBudevadm settle \fR\fB[options]\fR +.HP \w'\fBudevadm\ control\ \fR\fB\fIoption\fR\fR\ 'u +\fBudevadm control \fR\fB\fIoption\fR\fR +.HP \w'\fBudevadm\ monitor\ \fR\fB[options]\fR\ 'u +\fBudevadm monitor \fR\fB[options]\fR +.HP \w'\fBudevadm\ test\ \fR\fB[options]\fR\fB\ \fR\fB\fIdevpath\fR\fR\ 'u +\fBudevadm test \fR\fB[options]\fR\fB \fR\fB\fIdevpath\fR\fR +.HP \w'\fBudevadm\ test\-builtin\ \fR\fB[options]\fR\fB\ \fR\fB\fIcommand\fR\fR\fB\ \fR\fB\fIdevpath\fR\fR\ 'u +\fBudevadm test\-builtin \fR\fB[options]\fR\fB \fR\fB\fIcommand\fR\fR\fB \fR\fB\fIdevpath\fR\fR +.HP \w'\fBudevadm\ verify\fR\ 'u +\fBudevadm verify\fR [options...] [\fIfile\fR...] +.HP \w'\fBudevadm\ wait\ \fR\fB[options]\fR\fB\ \fR\fB\fIdevice|syspath\fR\fR\ 'u +\fBudevadm wait \fR\fB[options]\fR\fB \fR\fB\fIdevice|syspath\fR\fR +.HP \w'\fBudevadm\ lock\ \fR\fB[options]\fR\fB\ \fR\fB\fIcommand\fR\fR\ 'u +\fBudevadm lock \fR\fB[options]\fR\fB \fR\fB\fIcommand\fR\fR +.SH "DESCRIPTION" +.PP +\fBudevadm\fR +expects a command and command specific options\&. It controls the runtime behavior of +\fBsystemd\-udevd\fR, requests kernel events, manages the event queue, and provides simple debugging mechanisms\&. +.SH "OPTIONS" +.PP +\fB\-d\fR, \fB\-\-debug\fR +.RS 4 +Print debug messages to standard error\&. This option is implied in +\fBudevadm test\fR +and +\fBudevadm test\-builtin\fR +commands\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.SS "udevadm info [\fIoptions\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR...]" +.PP +Query the udev database for device information\&. +.PP +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 +/dev/), a sys path (in which case it must start with +/sys/), or a systemd device unit name (in which case it must end with +"\&.device", see +\fBsystemd.device\fR(5))\&. +.PP +\fB\-q\fR, \fB\-\-query=\fR\fB\fITYPE\fR\fR +.RS 4 +Query the database for the specified type of device data\&. Valid +\fITYPE\fRs are: +\fBname\fR, +\fBsymlink\fR, +\fBpath\fR, +\fBproperty\fR, +\fBall\fR\&. +.RE +.PP +\fB\-\-property=\fR\fB\fINAME\fR\fR +.RS 4 +When showing device properties using the +\fB\-\-query=property\fR +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\&. +.sp +Added in version 250\&. +.RE +.PP +\fB\-\-value\fR +.RS 4 +When showing device properties using the +\fB\-\-query=property\fR +option, print only their values, and skip the property name and +"="\&. +.sp +Cannot be used together with +\fB\-x/\-\-export\fR +or +\fB\-P/\-\-export\-prefix\fR\&. +.sp +Added in version 250\&. +.RE +.PP +\fB\-p\fR, \fB\-\-path=\fR\fB\fIDEVPATH\fR\fR +.RS 4 +The +/sys/ +path of the device to query, e\&.g\&. +[/sys/]/class/block/sda\&. This option is an alternative to the positional argument with a +/sys/ +prefix\&. +\fBudevadm info \-\-path=/class/block/sda\fR +is equivalent to +\fBudevadm info /sys/class/block/sda\fR\&. +.RE +.PP +\fB\-n\fR, \fB\-\-name=\fR\fB\fIFILE\fR\fR +.RS 4 +The name of the device node or a symlink to query, e\&.g\&. +[/dev/]/sda\&. This option is an alternative to the positional argument with a +/dev/ +prefix\&. +\fBudevadm info \-\-name=sda\fR +is equivalent to +\fBudevadm info /dev/sda\fR\&. +.RE +.PP +\fB\-r\fR, \fB\-\-root\fR +.RS 4 +Print absolute paths in +\fBname\fR +or +\fBsymlink\fR +query\&. +.RE +.PP +\fB\-a\fR, \fB\-\-attribute\-walk\fR +.RS 4 +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\&. +.RE +.PP +\fB\-t\fR, \fB\-\-tree\fR +.RS 4 +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\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-x\fR, \fB\-\-export\fR +.RS 4 +Print output as key/value pairs\&. Values are enclosed in single quotes\&. This takes effects only when +\fB\-\-query=property\fR +or +\fB\-\-device\-id\-of\-file=\fR\fB\fIFILE\fR\fR +is specified\&. +.RE +.PP +\fB\-P\fR, \fB\-\-export\-prefix=\fR\fB\fINAME\fR\fR +.RS 4 +Add a prefix to the key name of exported values\&. This implies +\fB\-\-export\fR\&. +.RE +.PP +\fB\-d\fR, \fB\-\-device\-id\-of\-file=\fR\fB\fIFILE\fR\fR +.RS 4 +Print major/minor numbers of the underlying device, where the file lives on\&. If this is specified, all positional arguments are ignored\&. +.RE +.PP +\fB\-e\fR, \fB\-\-export\-db\fR +.RS 4 +Export the content of the udev database\&. +.RE +.PP +\fB\-c\fR, \fB\-\-cleanup\-db\fR +.RS 4 +Cleanup the udev database\&. +.RE +.PP +\fB\-w\fR\fB[SECONDS]\fR, \fB\-\-wait\-for\-initialization\fR\fB[=SECONDS]\fR +.RS 4 +Wait for device to be initialized\&. If argument +\fISECONDS\fR +is not specified, the default is to wait forever\&. +.sp +Added in version 243\&. +.RE +.PP +\fB\-\-subsystem\-match\fR\fB[=SUBSYSTEM]\fR, \fB\-\-subsystem\-nomatch\fR\fB[=SUBSYSTEM]\fR +.RS 4 +When used with +\fB\-\-export\-db\fR, only show devices of or not of the given subsystem respectively\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-attr\-match\fR\fB[=FILE[=VALUE]]\fR, \fB\-\-attr\-nomatch\fR\fB[=FILE[=VALUE]]\fR +.RS 4 +When used with +\fB\-\-export\-db\fR, only show devices matching or not matching the given attribute respectively\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-property\-match\fR\fB[=KEY=VALUE]\fR +.RS 4 +When used with +\fB\-\-export\-db\fR, only show devices matching the given property and value\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-tag\-match\fR\fB[=TAG]\fR +.RS 4 +When used with +\fB\-\-export\-db\fR, only show devices with the given tag\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-sysname\-match\fR\fB[=NAME]\fR +.RS 4 +When used with +\fB\-\-export\-db\fR, only show devices with the given +"/sys" +path\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-name\-match\fR\fB[=NAME]\fR +.RS 4 +When used with +\fB\-\-export\-db\fR, only show devices with the given name in +"/dev"\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-parent\-match\fR\fB[=NAME]\fR +.RS 4 +When used with +\fB\-\-export\-db\fR, only show devices with the given parent device\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-initialized\-match\fR, \fB\-\-initialized\-nomatch\fR +.RS 4 +When used with +\fB\-\-export\-db\fR, only show devices that are initialized or not initialized respectively\&. +.sp +Added in version 255\&. +.RE +.PP +\fB\-\-json=\fR\fIMODE\fR +.RS 4 +Shows output formatted as JSON\&. Expects one of +"short" +(for the shortest possible output without any redundant whitespace or line breaks), +"pretty" +(for a pretty version of the same, with indentation and line breaks) or +"off" +(to turn off JSON output, the default)\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +\fB\-\-no\-pager\fR +.RS 4 +Do not pipe output into a pager\&. +.RE +.PP +The generated output shows the current device database entry in a terse format\&. Each line shown is prefixed with one of the following characters: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table\ \&1.\ \&udevadm info output prefixes +.TS +allbox tab(:); +lB lB. +T{ +Prefix +T}:T{ +Meaning +T} +.T& +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l +l l. +T{ +"P:" +T}:T{ +Device path in /sys/ +T} +T{ +"M:" +T}:T{ +Device name in /sys/ (i\&.e\&. the last component of "P:") +T} +T{ +"R:" +T}:T{ +Device number in /sys/ (i\&.e\&. the numeric suffix of the last component of "P:") +T} +T{ +"U:" +T}:T{ +Kernel subsystem +T} +T{ +"T:" +T}:T{ +Kernel device type within subsystem +T} +T{ +"D:" +T}:T{ +Kernel device node major/minor +T} +T{ +"I:" +T}:T{ +Network interface index +T} +T{ +"N:" +T}:T{ +Kernel device node name +T} +T{ +"L:" +T}:T{ +Device node symlink priority +T} +T{ +"S:" +T}:T{ +Device node symlink +T} +T{ +"Q:" +T}:T{ +Block device sequence number (DISKSEQ) +T} +T{ +"V:" +T}:T{ +Attached driver +T} +T{ +"E:" +T}:T{ +Device property +T} +.TE +.sp 1 +.SS "udevadm trigger [\fIoptions\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]" +.PP +Request device events from the kernel\&. Primarily used to replay events at system coldplug time\&. +.PP +Takes device specifications as positional arguments\&. See the description of +\fBinfo\fR +above\&. +.PP +\fB\-v\fR, \fB\-\-verbose\fR +.RS 4 +Print the list of devices which will be triggered\&. +.RE +.PP +\fB\-n\fR, \fB\-\-dry\-run\fR +.RS 4 +Do not actually trigger the event\&. +.RE +.PP +\fB\-q\fR, \fB\-\-quiet\fR +.RS 4 +Suppress error logging in triggering events\&. +.sp +Added in version 248\&. +.RE +.PP +\fB\-t\fR, \fB\-\-type=\fR\fB\fITYPE\fR\fR +.RS 4 +Trigger a specific type of devices\&. Valid types are +"all", +"devices", and +"subsystems"\&. The default value is +"devices"\&. +.RE +.PP +\fB\-c\fR, \fB\-\-action=\fR\fB\fIACTION\fR\fR +.RS 4 +Type of event to be triggered\&. Possible actions are +"add", +"remove", +"change", +"move", +"online", +"offline", +"bind", and +"unbind"\&. Also, the special value +"help" +can be used to list the possible actions\&. The default value is +"change"\&. +.RE +.PP +\fB\-\-prioritized\-subsystem=\fR\fB\fISUBSYSTEM\fR\fI[,\fISUBSYSTEM\fR\&...]\fR\fR +.RS 4 +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 +\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, +\fB\-\-prioritized\-subsystem=block \-\-prioritized\-subsystem=net\fR +is equivalent to +\fB\-\-prioritized\-subsystem=block,net\fR\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-s\fR, \fB\-\-subsystem\-match=\fR\fB\fISUBSYSTEM\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-S\fR, \fB\-\-subsystem\-nomatch=\fR\fB\fISUBSYSTEM\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-a\fR, \fB\-\-attr\-match=\fR\fB\fIATTRIBUTE\fR\fR\fB=\fR\fB\fIVALUE\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-A\fR, \fB\-\-attr\-nomatch=\fR\fB\fIATTRIBUTE\fR\fR\fB=\fR\fB\fIVALUE\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-p\fR, \fB\-\-property\-match=\fR\fB\fIPROPERTY\fR\fR\fB=\fR\fB\fIVALUE\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-g\fR, \fB\-\-tag\-match=\fR\fB\fITAG\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-y\fR, \fB\-\-sysname\-match=\fR\fB\fINAME\fR\fR +.RS 4 +Trigger events for devices for which the last component (i\&.e\&. the filename) of the +/sys/ +path matches the specified +\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 +\fINAME\fR +are triggered\&. +.RE +.PP +\fB\-\-name\-match=\fR\fB\fINAME\fR\fR +.RS 4 +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\&. +.sp +Added in version 218\&. +.RE +.PP +\fB\-b\fR, \fB\-\-parent\-match=\fR\fB\fISYSPATH\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-\-initialized\-match\fR, \fB\-\-initialized\-nomatch\fR +.RS 4 +When +\fB\-\-initialized\-match\fR +is specified, trigger events for devices that are already initialized by +\fBsystemd\-udevd\fR, and skip devices that are not initialized yet\&. +.sp +When +\fB\-\-initialized\-nomatch\fR +is specified, trigger events for devices that are not initialized by +\fBsystemd\-udevd\fR +yet, and skip devices that are already initialized\&. +.sp +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\&. +.sp +WARNING: +\fB\-\-initialized\-nomatch\fR +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\&. +"ATTRS" +or +"IMPORT{parent}" +keys, see +\fBudev\fR(7) +for more details), the final state of the device becomes easily unstable with this option\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-w\fR, \fB\-\-settle\fR +.RS 4 +Apart from triggering events, also waits for those events to finish\&. Note that this is different from calling +\fBudevadm settle\fR\&. +\fBudevadm settle\fR +waits for all events to finish\&. This option only waits for events triggered by the same command to finish\&. +.sp +Added in version 238\&. +.RE +.PP +\fB\-\-uuid\fR +.RS 4 +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 +"SYNTH_UUID=" +property) and may be used to track delivery of the generated events\&. +.sp +Added in version 249\&. +.RE +.PP +\fB\-\-wait\-daemon[=\fR\fB\fISECONDS\fR\fR\fB]\fR +.RS 4 +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 +\fBudevadm control \-\-ping\fR +before +\fBudevadm trigger\fR\&. +.sp +Added in version 241\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +In addition, optional positional arguments can be used to specify device names or sys paths\&. They must start with +/dev/ +or +/sys/ +respectively\&. +.SS "udevadm settle [\fIoptions\fR]" +.PP +Watches the udev event queue, and exits if all current events are handled\&. +.PP +\fB\-t\fR, \fB\-\-timeout=\fR\fB\fISECONDS\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-E\fR, \fB\-\-exit\-if\-exists=\fR\fB\fIFILE\fR\fR +.RS 4 +Stop waiting if file exists\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +See +\fBsystemd-udev-settle.service\fR(8) +for more information\&. +.SS "udevadm control \fIoption\fR" +.PP +Modify the internal state of the running udev daemon\&. +.PP +\fB\-e\fR, \fB\-\-exit\fR +.RS 4 +Signal and wait for systemd\-udevd to exit\&. No option except for +\fB\-\-timeout\fR +can be specified after this option\&. Note that +systemd\-udevd\&.service +contains +\fBRestart=always\fR +and so as a result, this option restarts systemd\-udevd\&. If you want to stop +systemd\-udevd\&.service, please use the following: +.sp +.if n \{\ +.RS 4 +.\} +.nf +systemctl stop systemd\-udevd\-control\&.socket systemd\-udevd\-kernel\&.socket systemd\-udevd\&.service +.fi +.if n \{\ +.RE +.\} +.sp +.RE +.PP +\fB\-l\fR, \fB\-\-log\-level=\fR\fB\fIvalue\fR\fR +.RS 4 +Set the internal log level of +systemd\-udevd\&. Valid values are the numerical syslog priorities or their textual representations: +\fBemerg\fR, +\fBalert\fR, +\fBcrit\fR, +\fBerr\fR, +\fBwarning\fR, +\fBnotice\fR, +\fBinfo\fR, and +\fBdebug\fR\&. +.RE +.PP +\fB\-s\fR, \fB\-\-stop\-exec\-queue\fR +.RS 4 +Signal systemd\-udevd to stop executing new events\&. Incoming events will be queued\&. +.RE +.PP +\fB\-S\fR, \fB\-\-start\-exec\-queue\fR +.RS 4 +Signal systemd\-udevd to enable the execution of events\&. +.RE +.PP +\fB\-R\fR, \fB\-\-reload\fR +.RS 4 +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\&. +.RE +.PP +\fB\-p\fR, \fB\-\-property=\fR\fB\fIKEY\fR\fR\fB=\fR\fB\fIvalue\fR\fR +.RS 4 +Set a global property for all events\&. +.RE +.PP +\fB\-m\fR, \fB\-\-children\-max=\fR\fIvalue\fR +.RS 4 +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\&. +.RE +.PP +\fB\-\-ping\fR +.RS 4 +Send a ping message to systemd\-udevd and wait for the reply\&. This may be useful to check that systemd\-udevd daemon is running\&. +.sp +Added in version 241\&. +.RE +.PP +\fB\-t\fR, \fB\-\-timeout=\fR\fIseconds\fR +.RS 4 +The maximum number of seconds to wait for a reply from systemd\-udevd\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.SS "udevadm monitor [\fIoptions\fR]" +.PP +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\&. +.PP +\fB\-k\fR, \fB\-\-kernel\fR +.RS 4 +Print the kernel uevents\&. +.RE +.PP +\fB\-u\fR, \fB\-\-udev\fR +.RS 4 +Print the udev event after the rule processing\&. +.RE +.PP +\fB\-p\fR, \fB\-\-property\fR +.RS 4 +Also print the properties of the event\&. +.RE +.PP +\fB\-s\fR, \fB\-\-subsystem\-match=\fR\fB\fIstring[/string]\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-t\fR, \fB\-\-tag\-match=\fR\fB\fIstring\fR\fR +.RS 4 +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\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.SS "udevadm test [\fIoptions\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]" +.PP +Simulate a udev event run for the given device, and print debug output\&. +.PP +\fB\-a\fR, \fB\-\-action=\fR\fB\fIACTION\fR\fR +.RS 4 +Type of event to be simulated\&. Possible actions are +"add", +"remove", +"change", +"move", +"online", +"offline", +"bind", and +"unbind"\&. Also, the special value +"help" +can be used to list the possible actions\&. The default value is +"add"\&. +.RE +.PP +\fB\-N\fR, \fB\-\-resolve\-names=\fR\fB\fBearly\fR\fR\fB|\fR\fB\fBlate\fR\fR\fB|\fR\fB\fBnever\fR\fR +.RS 4 +Specify when udevadm should resolve names of users and groups\&. When set to +\fBearly\fR +(the default), names will be resolved when the rules are parsed\&. When set to +\fBlate\fR, names will be resolved for every event\&. When set to +\fBnever\fR, names will never be resolved and all devices will be owned by root\&. +.sp +Added in version 209\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.SS "udevadm test\-builtin [\fIoptions\fR] [\fIcommand\fR] [\fIdevpath\fR|\fIfile\fR|\fIunit\fR]" +.PP +Run a built\-in command +\fICOMMAND\fR +for device +\fIDEVPATH\fR, and print debug output\&. +.PP +\fB\-a\fR, \fB\-\-action=\fR\fB\fIACTION\fR\fR +.RS 4 +Type of event to be simulated\&. Possible actions are +"add", +"remove", +"change", +"move", +"online", +"offline", +"bind", and +"unbind"\&. Also, the special value +"help" +can be used to list the possible actions\&. The default value is +"add"\&. +.sp +Added in version 250\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.PP +\fB\-\-version\fR +.RS 4 +Print a short version string and exit\&. +.RE +.SS "udevadm verify [\fIoptions\fR] [\fIfile\fR...] \&..." +.PP +Verify syntactic, semantic, and stylistic correctness of udev rules files\&. +.PP +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\&. +.PP +The exit status is +\fB0\fR +if all specified udev rules files are syntactically, semantically, and stylistically correct, and a non\-zero error code otherwise\&. +.PP +\fB\-N\fR, \fB\-\-resolve\-names=\fR\fB\fBearly\fR\fR\fB|\fR\fB\fBnever\fR\fR +.RS 4 +Specify when udevadm should resolve names of users and groups\&. When set to +\fBearly\fR +(the default), names will be resolved when the rules are parsed\&. When set to +\fBnever\fR, names will never be resolved\&. +.sp +Added in version 254\&. +.RE +.PP +\fB\-\-root=\fR\fB\fIPATH\fR\fR +.RS 4 +When looking for udev rules files located in udev/rules\&.d directories, operate on files underneath the specified root path +\fIPATH\fR\&. +.sp +Added in version 254\&. +.RE +.PP +\fB\-\-no\-summary\fR +.RS 4 +Do not show summary\&. +.sp +Added in version 254\&. +.RE +.PP +\fB\-\-no\-style\fR +.RS 4 +Ignore style issues\&. When specified, even if style issues are found in udev rules files, the exit status is +\fB0\fR +if no syntactic or semantic errors are found\&. +.sp +Added in version 254\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.SS "udevadm wait [\fIoptions\fR] [\fIdevice|syspath\fR] \&..." +.PP +Wait for devices or device symlinks being created and initialized by +\fBsystemd\-udevd\fR\&. Each device path must start with +"/dev/" +or +"/sys/", e\&.g\&. +"/dev/sda", +"/dev/disk/by\-path/pci\-0000:3c:00\&.0\-nvme\-1\-part1", +"/sys/devices/pci0000:00/0000:00:1f\&.6/net/eth0", or +"/sys/class/net/eth0"\&. This can take multiple devices\&. This may be useful for waiting for devices being processed by +\fBsystemd\-udevd\fR +after e\&.g\&. partitioning or formatting the devices\&. +.PP +\fB\-t\fR, \fB\-\-timeout=\fR\fB\fISECONDS\fR\fR +.RS 4 +Maximum number of seconds to wait for the specified devices or device symlinks being created, initialized, or removed\&. The default value is +"infinity"\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-initialized=\fR\fB\fIBOOL\fR\fR +.RS 4 +Check if +\fBsystemd\-udevd\fR +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\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-removed\fR +.RS 4 +When specified, the command wait for devices being removed instead of created or initialized\&. If this is specified, +\fB\-\-initialized=\fR +will be ignored\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-settle\fR +.RS 4 +When specified, also watches the udev event queue, and wait for all queued events being processed by +\fBsystemd\-udevd\fR\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.SS "udevadm lock [\fIoptions\fR] [\fIcommand\fR] \&..." +.PP +\fBudevadm lock\fR +takes an (advisory) exclusive lock on a block device (or all specified devices), as per +\m[blue]\fBLocking Block Device Access\fR\m[]\&\s-2\u[1]\d\s+2 +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 +\fBudevadm lock\fR\&. +.PP +This tool is in particular useful to ensure that +\fBsystemd-udevd.service\fR(8) +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 +\fBsfdisk\fR(8)\*(Aqs +\fB\-\-lock\fR +switch\&. +.PP +The command expects at least one block device specified via +\fB\-\-device=\fR +or +\fB\-\-backing=\fR, and a command line to execute as arguments\&. +.PP +\fB\-\-device=\fR\fB\fIDEVICE\fR\fR, \fB\-d \fR\fB\fIDEVICE\fR\fR +.RS 4 +Takes a path to a device node of the device to lock\&. This switch may be used multiple times (and in combination with +\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\&. +.sp +This switch must be used at least once, to specify at least one device to lock\&. (Alternatively, use +\fB\-\-backing=\fR, see below\&.) +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-backing=\fR\fB\fIPATH\fR\fR, \fB\-b \fR\fB\fIPATH\fR\fR +.RS 4 +If a path to a device node is specified, identical to +\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 +\fB\-\-device=\fR\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-timeout=\fR\fB\fISECS\fR\fR, \fB\-t \fR\fB\fISECS\fR\fR +.RS 4 +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 +\fBsystemd.time\fR(7)\&. If specified as zero the lock is attempted and if not successful the invocation will immediately fail\&. If passed as +"infinity" +(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\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-\-print\fR, \fB\-p\fR +.RS 4 +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 +\fB\-\-device=\fR +and +\fB\-\-backing=\fR +switches specified in case these resolve to the same "whole" devices\&. +.sp +Added in version 251\&. +.RE +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +Print a short help text and exit\&. +.RE +.SH "INITIALIZED DEVICES" +.PP +Initialized devices are those for which at least one udev rule already completed execution \(en for any action but +"remove" +\(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 +"remove" +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)\&. +.SH "EXAMPLE" +.PP +\fBExample\ \&1.\ \&Format a File System\fR +.PP +Take a lock on the backing block device while creating a file system, to ensure that +\fBsystemd\-udevd\fR +doesn\*(Aqt probe or announce the new superblock before it is comprehensively written: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# udevadm lock \-\-device=/dev/sda1 mkfs\&.ext4 /dev/sda1 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&2.\ \&Format a RAID File System\fR +.PP +Similar, but take locks on multiple devices at once: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# udevadm lock \-\-device=/dev/sda1 \-\-device=/dev/sdb1 mkfs\&.btrfs /dev/sda1 /dev/sdb1 +.fi +.if n \{\ +.RE +.\} +.PP +\fBExample\ \&3.\ \&Copy in a File System\fR +.PP +Take a lock on the backing block device while copying in a prepared file system image, to ensure that +\fBsystemd\-udevd\fR +doesn\*(Aqt probe or announce the new superblock before it is fully written: +.sp +.if n \{\ +.RS 4 +.\} +.nf +# udevadm lock \-d /dev/sda1 dd if=fs\&.raw of=/dev/sda1 +.fi +.if n \{\ +.RE +.\} +.SH "SEE ALSO" +.PP +\fBudev\fR(7), +\fBsystemd-udevd.service\fR(8) +.SH "NOTES" +.IP " 1." 4 +Locking Block Device Access +.RS 4 +\%https://systemd.io/BLOCK_DEVICE_LOCKING +.RE |