HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/udevadm.xml
Git blob: fc09a6dfcf0fed251fdd17b9f18da4b7f23ab2c4
Lines 1001–1362 of 1,362
<para>Verify syntactic, semantic, and stylistic correctness of udev rules files.</para>
<para>Positional arguments can be used to specify one or more files to check. Each argument must be an
absolute path to a udev rules file or a directory that contains rules files, or a file name of udev
rules file (e.g. <filename>99-systemd.rules</filename>). If a file name is specified, the file will be
searched in the <filename>udev/rules.d</filename> directories that are processed by
<command>systemd-udevd</command>, and searched in the current working directory if not found. If no
files are specified, the udev rules are read from the files located in the same
<filename>udev/rules.d</filename> directories that are processed by <command>systemd-udevd</command>.
See <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> for more
details about the search paths.</para>
<para>The exit status is <constant>0</constant> if all specified udev
rules files are syntactically, semantically, and stylistically correct,
and a non-zero error code otherwise.</para>
<variablelist>
<varlistentry>
<term><option>-N</option></term>
<term><option>--resolve-names=<constant>early</constant>|<constant>late</constant>|<constant>never</constant></option></term>
<listitem>
<para>Specify when <command>udevadm</command> should resolve names of users and groups specified
in udev rules. When set to <constant>early</constant> (the default), names will be resolved when
the rules are parsed. When set to <constant>late</constant>, names will not be verified, as
<command>systemd-udevd</command> resolves names during each event being processed. When set to
<constant>never</constant>, names will never be resolved and relevant rules will be ignored.
</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--root=<replaceable>PATH</replaceable></option></term>
<listitem>
<para>When looking for udev rules files located in the <filename>udev/rules.d</filename>
directories, operate on files underneath the specified root path <replaceable>PATH</replaceable>.
When a file name is specified, and it is not found in the <filename>udev/rules.d</filename>
directories, the file will be searched in the specified root path
<replaceable>PATH</replaceable>, rather than the current working directory.</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-summary</option></term>
<listitem>
<para>Do not show summary.</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--no-style</option></term>
<listitem>
<para>Ignore style issues. When specified, even if style issues are found in udev rules files,
the exit status is <constant>0</constant> if no syntactic or semantic errors are found.</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>udevadm cat
<optional><replaceable>options</replaceable>…</optional>
<optional><replaceable>file</replaceable>…</optional>
</title>
<para>Show udev rules files or udev.conf.</para>
<para>Positional arguments can be used to specify one or more files to show. Each argument must be an
absolute path to a udev rules file or a directory that contains rules files, or a file name of udev
rules file (e.g. <filename>99-systemd.rules</filename>). If a file name is specified, the file will be
searched in the <filename>udev/rules.d</filename> directories that are processed by
<command>systemd-udevd</command>, and searched in the current working directory if not found. If no
files are specified, the udev rules are read from the files located in the same
<filename>udev/rules.d</filename> directories that are processed by <command>systemd-udevd</command>.
See <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry> for more
details about the search paths.</para>
<variablelist>
<varlistentry>
<term><option>--root=<replaceable>PATH</replaceable></option></term>
<listitem>
<para>When looking for udev rules files located in the <filename>udev/rules.d</filename>
directories, operate on files underneath the specified root path <replaceable>PATH</replaceable>.
When a file name is specified, and it is not found in the <filename>udev/rules.d</filename>
directories, the file will be searched in the specified root path
<replaceable>PATH</replaceable>, rather than the current working directory.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--tldr</option></term>
<listitem>
<para>Only print the "interesting" parts of the configuration files, skipping comments and empty
lines and section headers followed only by comments and empty lines.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--config</option></term>
<listitem>
<para>Shows
<citerefentry><refentrytitle>udev.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
files, rather than udev rules files. When specified, no udev rules file cannot be specified.
</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>udevadm wait
<optional><replaceable>options</replaceable>…</optional>
<replaceable>devpath|syspath</replaceable>…
</title>
<para>Wait for devices or device symlinks being created and initialized by
<command>systemd-udevd</command>. Each device path must start with
<literal>/dev/</literal> or <literal>/sys/</literal>, e.g. <literal>/dev/sda</literal>,
<literal>/dev/disk/by-path/pci-0000:3c:00.0-nvme-1-part1</literal>,
<literal>/sys/devices/pci0000:00/0000:00:1f.6/net/eth0</literal>, or
<literal>/sys/class/net/eth0</literal>. This can take multiple devices. This may be useful for
waiting for devices being processed by <command>systemd-udevd</command> after e.g. partitioning
or formatting the devices.</para>
<variablelist>
<varlistentry>
<term><option>-t</option></term>
<term><option>--timeout=<replaceable>SECONDS</replaceable></option></term>
<listitem>
<para>Maximum number of seconds to wait for the specified devices or device symlinks being
created, initialized, or removed. The default value is <literal>infinity</literal>.</para>
<xi:include href="version-info.xml" xpointer="v251"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--initialized=<replaceable>BOOL</replaceable></option></term>
<listitem>
<para>Check if <command>systemd-udevd</command> 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.</para>
<xi:include href="version-info.xml" xpointer="v251"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--removed</option></term>
<listitem>
<para>When specified, the command wait for devices being removed instead of created or
initialized. If this is specified, <option>--initialized=</option> will be ignored.</para>
<xi:include href="version-info.xml" xpointer="v251"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--settle</option></term>
<listitem>
<para>When specified, also watches the udev event queue, and wait for all queued events
being processed by <command>systemd-udevd</command>.</para>
<xi:include href="version-info.xml" xpointer="v251"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>udevadm lock
<optional><replaceable>options</replaceable>…</optional>
<replaceable>command</replaceable>…
</title>
<para><command>udevadm lock</command> takes an (advisory) exclusive lock on a block device (or all
specified devices), as per <ulink url="https://systemd.io/BLOCK_DEVICE_LOCKING">Locking Block Device
Access</ulink> 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 <command>udevadm
lock</command>.</para>
<para>This tool is in particular useful to ensure that
<citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
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
<citerefentry project='man-pages'><refentrytitle>sfdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
<option>--lock</option> switch.</para>
<para>The command expects at least one block device specified via <option>--device=</option> or
<option>--backing=</option>, and a command line to execute as arguments.</para>
<variablelist>
<varlistentry>
<term><option>--device=<replaceable>DEVICE</replaceable></option></term>
<term><option>-d <replaceable>DEVICE</replaceable></option></term>
<listitem>
<para>Takes a path to a device node of the device to lock. This switch may be used
multiple times (and in combination with <option>--backing=</option>) 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.</para>
<para>This switch must be used at least once, to specify at least one device to
lock. (Alternatively, use <option>--backing=</option>, see below.)</para>
<xi:include href="version-info.xml" xpointer="v251"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--backing=<replaceable>PATH</replaceable></option></term>
<term><option>-b <replaceable>PATH</replaceable></option></term>
<listitem>
<para>If a path to a device node is specified, identical to
<option>--device=</option>. 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
<option>--device=</option>.</para>
<xi:include href="version-info.xml" xpointer="v251"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--timeout=<replaceable>SECS</replaceable></option></term>
<term><option>-t <replaceable>SECS</replaceable></option></term>
<listitem>
<para>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
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>. If
specified as zero the lock is attempted and if not successful the invocation will immediately
fail. If passed as <literal>infinity</literal> (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.</para>
<xi:include href="version-info.xml" xpointer="v251"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--print</option></term>
<term><option>-p</option></term>
<listitem>
<para>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'd be locked). Note that the number of lines
printed here can be less than the number of <option>--device=</option> and
<option>--backing=</option> switches specified in case these resolve to the same "whole"
devices.</para>
<xi:include href="version-info.xml" xpointer="v251"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>Initialized Devices</title>
<para>Initialized devices are those for which at least one udev rule already completed execution
– for any action but <literal>remove</literal> — 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
<literal>remove</literal> 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).</para>
</refsect1>
<refsect1>
<title>Example</title>
<example>
<title>Format a File System</title>
<para>Take a lock on the backing block device while creating a file system, to ensure that
<command>systemd-udevd</command> does not probe or announce the new superblock before it is
comprehensively written:</para>
<programlisting># udevadm lock --device=/dev/sda1 mkfs.ext4 /dev/sda1</programlisting>
</example>
<example>
<title>Format a RAID File System</title>
<para>Similar, but take locks on multiple devices at once:</para>
<programlisting># udevadm lock --device=/dev/sda1 --device=/dev/sdb1 mkfs.btrfs /dev/sda1 /dev/sdb1</programlisting>
</example>
<example>
<title>Copy in a File System</title>
<para>Take a lock on the backing block device while copying in a prepared file system image, to ensure
that <command>systemd-udevd</command> does not probe or announce the new superblock before it is fully
written:</para>
<programlisting># udevadm lock -d /dev/sda1 dd if=fs.raw of=/dev/sda1</programlisting>
</example>
<example>
<title>Predict Network Interface Renaming</title>
<para>To predict a network interface name, <command>udevadm test</command> can be used:</para>
<programlisting>$ udevadm test /sys/class/net/wlan0 --json=pretty 2>/dev/null | jq .networkInterface.name
"wlp59s0"</programlisting>
</example>
<example>
<title>Predict Symbolic links of a Device Node</title>
<para>To predict symbolic links to a device node, <command>udevadm test</command> can be used:</para>
<programlisting>$ udevadm test /dev/nvme0n1p1 --json=pretty 2>/dev/null | jq .node.symlinks
[
"/dev/disk/by-diskseq/1-part1",
"/dev/disk/by-id/nvme-WDC_PC_SN720_SDAQNTW-512G-1001_192290802247-part1",
"/dev/disk/by-id/nvme-WDC_PC_SN720_SDAQNTW-512G-1001_192290802247_1-part1",
"/dev/disk/by-id/nvme-eui.1922908022470001001b448b44ccb9d6-part1",
"/dev/disk/by-path/pci-0000:3c:00.0-nvme-1-part/by-partnum/1",
"/dev/disk/by-path/pci-0000:3c:00.0-nvme-1-part1"
]
$ udevadm test /dev/input/event3 --json=pretty 2>/dev/null | jq .node.symlinks
[
"/dev/input/by-path/platform-i8042-serio-0-event-kbd"
]</programlisting>
</example>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>udev.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>