HALF ECHO LEARN / REFERENCE COLLECTION

v262.2

man/udevadm.xml

65,482 bytesGit mode 100644Download original fileLGPL-2.1-or-later

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>