From acdba85e0e2bf229f356ad09a2b880e89224715d Mon Sep 17 00:00:00 2001
From: "Dmitry V. Levin" <ldv@strace.io>
Date: Thu, 2 Mar 2023 08:00:00 +0000
Subject: udevadm: introduce new 'verify' command

We seem to have no tool to verify udev rule files.  There is a simple
udev rules syntax checker in the tree, test/rule-syntax-check.py, but
it is too simple to detect less trivial issues not detected by udev,
e.g. redundant comparisons (#26593) or labels without references.

Such a tool would be beneficial not only for maintaining udev rules
distributed along with udev, but also and even more so for maintaining
third party udev rules that are more likely to have issues with syntax
and semantic correctness.

Implement a udev rules syntax and semantics checker in the form of
'udevadm verify [OPTIONS] FILE...' command that is based on
udev_rules_parse_file() interface and would apply further checks
on top of it in subsequent commits.

Resolves: #26606
---
 man/udevadm.xml | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

(limited to 'man/udevadm.xml')

diff --git a/man/udevadm.xml b/man/udevadm.xml
index 33af155021..95b8da2b0a 100644
--- a/man/udevadm.xml
+++ b/man/udevadm.xml
@@ -48,6 +48,11 @@
     <cmdsynopsis>
       <command>udevadm test-builtin <optional>options</optional> <replaceable>command</replaceable> <replaceable>devpath</replaceable></command>
     </cmdsynopsis>
+    <cmdsynopsis>
+      <command>udevadm verify</command>
+      <arg choice="opt" rep="repeat">options</arg>
+      <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
+    </cmdsynopsis>
     <cmdsynopsis>
       <command>udevadm wait <optional>options</optional> <replaceable>device|syspath</replaceable></command>
     </cmdsynopsis>
@@ -737,6 +742,37 @@
       </variablelist>
     </refsect2>
 
+    <refsect2>
+      <title>udevadm verify
+      <arg choice="opt"><replaceable>options</replaceable></arg>
+      <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg>
+      …
+      </title>
+
+      <para>Verify syntactic and semantic correctness of udev rules files.</para>
+
+      <para>Positional arguments should be used to specify one or more files to check.</para>
+
+      <para>The exit status is <constant>0</constant> if all specified udev rules files
+      are syntactically and semantically correct, and a non-zero error code otherwise.</para>
+
+      <variablelist>
+        <varlistentry>
+          <term><option>-N</option></term>
+          <term><option>--resolve-names=<constant>early</constant>|<constant>never</constant></option></term>
+          <listitem>
+            <para>Specify when udevadm should resolve names of users
+            and groups.  When set to <constant>early</constant> (the
+            default), names will be resolved when the rules are
+            parsed. When set to <constant>never</constant>, names will
+            never be resolved.</para>
+          </listitem>
+        </varlistentry>
+
+        <xi:include href="standard-options.xml" xpointer="help" />
+      </variablelist>
+    </refsect2>
+
     <refsect2>
       <title>udevadm wait
       <arg choice="opt"><replaceable>options</replaceable></arg>
-- 
cgit v1.2.1