From c26db0564086afb5cfcfdd00c1278b42e4d20649 Mon Sep 17 00:00:00 2001
From: Yu Watanabe <watanabe.yu+github@gmail.com>
Date: Tue, 4 Feb 2025 13:26:25 +0900
Subject: [PATCH] man/udevadm: add examples to get predictable interface name
 and persistent device node symlinks

Closes #23661.
---
 man/udevadm.xml | 35 ++++++++++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/man/udevadm.xml b/man/udevadm.xml
index c9e58e9cf57..4e1255bf4d6 100644
--- a/man/udevadm.xml
+++ b/man/udevadm.xml
@@ -879,7 +879,10 @@
       <optional><replaceable>devpath</replaceable>|<replaceable>file</replaceable>|<replaceable>unit</replaceable></optional>
       </title>
 
-      <para>Simulate a udev event run for the given device, and print debug output.</para>
+      <para>
+        Simulate a udev event run for the given device, and print debug output. The option
+        <option>--json=</option> may be useful for parsing the final result. See also Example section.
+      </para>
 
       <variablelist>
         <varlistentry>
@@ -1293,6 +1296,36 @@
 
       <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>
-- 
2.47.3