man: add SD_HWDB_FOREACH_PROPERTY with an example

3 files changed, 57 insertions, 1 deletions

diff --git a/man/hwdb-usb-device.c b/man/hwdb-usb-device.c
new file mode 100644
index 0000000000..8a4b86e7bd
--- /dev/null
+++ b/man/hwdb-usb-device.c
@@ -0,0 +1,28 @@
+#include <stdio.h>
+#include <stdint.h>
+#include <sd-hwdb.h>
+
+int print_usb_properties(uint16_t vid, uint16_t pid) {
+  char match[15];
+  sd_hwdb *hwdb;
+  const char *key, *value;
+  int r;
+
+  /* Match this USB vendor and product ID combination */
+  snprintf(match, sizeof match, "usb:v%04Xp%04X", vid, pid);
+
+  r = sd_hwdb_new(&hwdb);
+  if (r < 0)
+    return r;
+
+  SD_HWDB_FOREACH_PROPERTY(hwdb, match, key, value)
+    printf("%s: \"%s\" → \"%s\"\n", match, key, value);
+
+  sd_hwdb_unref(hwdb);
+  return 0;
+}
+
+int main(int argc, char **argv) {
+  print_usb_properties(0x046D, 0xC534);
+  return 0;
+}
diff --git a/man/rules/meson.build b/man/rules/meson.build
index d3457e7ccc..8c20c86544 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -560,7 +560,10 @@ manpages = [
   '3',
   ['sd_get_machine_names', 'sd_get_sessions', 'sd_get_uids'],
   'HAVE_PAM'],
- ['sd_hwdb_get', '3', ['sd_hwdb_enumerate', 'sd_hwdb_seek'], ''],
+ ['sd_hwdb_get',
+  '3',
+  ['SD_HWDB_FOREACH_PROPERTY', 'sd_hwdb_enumerate', 'sd_hwdb_seek'],
+  ''],
  ['sd_hwdb_new', '3', ['sd_hwdb_ref', 'sd_hwdb_unref'], ''],
  ['sd_id128_get_machine',
   '3',
diff --git a/man/sd_hwdb_get.xml b/man/sd_hwdb_get.xml
index b5c5b1cc6f..58e6e57e0f 100644
--- a/man/sd_hwdb_get.xml
+++ b/man/sd_hwdb_get.xml
@@ -18,6 +18,7 @@
     <refname>sd_hwdb_get</refname>
     <refname>sd_hwdb_seek</refname>
     <refname>sd_hwdb_enumerate</refname>
+    <refname>SD_HWDB_FOREACH_PROPERTY</refname>
 
     <refpurpose>Seek to a location in hwdb or access entries</refpurpose>
   </refnamediv>
@@ -47,6 +48,13 @@
         <paramdef>const char **<parameter>value</parameter></paramdef>
       </funcprototype>
 
+      <funcprototype>
+        <funcdef><function>SD_HWDB_FOREACH_PROPERTY</function></funcdef>
+        <paramdef>hwdb</paramdef>
+        <paramdef>modalias</paramdef>
+        <paramdef>key</paramdef>
+        <paramdef>value</paramdef>
+      </funcprototype>
     </funcsynopsis>
   </refsynopsisdiv>
 
@@ -75,6 +83,10 @@
     <parameter>modalias</parameter>, the combination of all matching key-value pairs is used. See
     <citerefentry><refentrytitle>hwdb</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
     details.</para>
+
+    <para>The <function>SD_HWDB_FOREACH_PROPERTY</function> macro combines
+    <function>sd_hwdb_seek()</function> and <function>sd_hwdb_enumerate()</function>. No error handling is
+    performed and interation simply stops on error. See the example below.</para>
   </refsect1>
 
   <refsect1>
@@ -119,6 +131,19 @@
   <xi:include href="libsystemd-pkgconfig.xml" />
 
   <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Look up hwdb entries for a USB device</title>
+
+      <programlisting><xi:include href="hwdb-usb-device.c" parse="text" /></programlisting>
+
+      <para>The effect is similar to calling <command>systemd-hwdb query usb:v046DpC534</command>.
+      </para>
+    </example>
+  </refsect1>
+
+  <refsect1>
     <title>See Also</title>
 
     <para>