docs: add man pages for `sd_device_enumerator_add_match_*` (#37589)

Add man pages for:
- `sd_device_enumerator_add_all_parents`
- `sd_device_enumerator_add_match_parent`
- `sd_device_enumerator_add_match_property`
- `sd_device_enumerator_add_match_property_required`
- `sd_device_enumerator_add_match_subsystem`
- `sd_device_enumerator_add_match_sysattr`
- `sd_device_enumerator_add_match_sysname`
- `sd_device_enumerator_add_match_tag`
- `sd_device_enumerator_add_nomatch_sysname`
- `sd_device_enumerator_allow_uninitialized`.

Related to #20929

diff --git a/man/meson.build b/man/meson.build
index d96c1a8af00e8c4f9881b0ba00d43dee7787b782..38bfb0646c826a02502bea4f23a5882713330ead 100644 (file)
--- a/man/meson.build
+++ b/man/meson.build
@@ -276,6 +276,7 @@ simple_examples = files(
         'sd-bus-container-read.c',
         'sd_bus_error-example.c',
         'sd_bus_service_reconnect.c',
+        'sd_device_enumerator_add_match_parent-example.c',
         'sd_device_enumerator_new-example.c',
         'send-unit-files-changed.c',
         'vtable-example.c',

diff --git a/man/rules/meson.build b/man/rules/meson.build
index 778b12c86a3965df9830e0e90b27d570d0aacea1..1ce5238a3dca64b7984a5c8bfa19f75ed1a97aaf 100644 (file)
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -524,6 +524,18 @@ manpages = [
    'sd_bus_track_unrefp'],
   ''],
  ['sd_bus_wait', '3', [], ''],
+ ['sd_device_enumerator_add_match_parent',
+  '3',
+  ['sd_device_enumerator_add_all_parents',
+   'sd_device_enumerator_add_match_property',
+   'sd_device_enumerator_add_match_property_required',
+   'sd_device_enumerator_add_match_subsystem',
+   'sd_device_enumerator_add_match_sysattr',
+   'sd_device_enumerator_add_match_sysname',
+   'sd_device_enumerator_add_match_tag',
+   'sd_device_enumerator_add_nomatch_sysname',
+   'sd_device_enumerator_allow_uninitialized'],
+  ''],
  ['sd_device_enumerator_new',
   '3',
   ['sd_device_enumerator_ref',

diff --git a/man/sd_device_enumerator_add_match_parent-example.c b/man/sd_device_enumerator_add_match_parent-example.c
new file mode 100644 (file)
index 0000000..f558db5
--- /dev/null
+++ b/man/sd_device_enumerator_add_match_parent-example.c
@@ -0,0 +1,47 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdbool.h>
+#include <stdio.h>
+#include <systemd/sd-device.h>
+
+int main(void) {
+    __attribute__((cleanup(sd_device_enumerator_unrefp))) sd_device_enumerator *enumerator = NULL;
+    sd_device *device;
+    int r;
+
+    /* Create a new device enumerator */
+    r = sd_device_enumerator_new(&enumerator);
+    if (r < 0) {
+        fprintf(stderr, "Failed to create device enumerator: %s\n", strerror(-r));
+        return 1;
+    }
+
+    /* Include only devices from the "usb" subsystem */
+    r = sd_device_enumerator_add_match_subsystem(enumerator, "usb", true);
+    if (r < 0) {
+        fprintf(stderr, "Failed to add subsystem match: %s\n", strerror(-r));
+        return 1;
+    }
+
+    /*
+     * Exclude devices where the "removable" sysattr is "0"
+     * These are typically non-removable devices like built-in USB interfaces
+     */
+    r = sd_device_enumerator_add_match_sysattr(enumerator, "removable", "0", false);
+    if (r < 0) {
+        fprintf(stderr, "Failed to add sysattr match: %s\n", strerror(-r));
+        return 1;
+    }
+
+    /* Begin enumerating matching devices */
+    for (device = sd_device_enumerator_get_device_first(enumerator);
+         device;
+         device = sd_device_enumerator_get_device_next(enumerator)) {
+        const char *syspath;
+
+        /* Get syspath for the device */
+        if (sd_device_get_syspath(device, &syspath) >= 0)
+            printf("Removable USB device found: %s\n", syspath);
+    }
+    return 0;
+}

diff --git a/man/sd_device_enumerator_add_match_parent.xml b/man/sd_device_enumerator_add_match_parent.xml
new file mode 100644 (file)
index 0000000..4ba1382
--- /dev/null
+++ b/man/sd_device_enumerator_add_match_parent.xml
@@ -0,0 +1,223 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentries PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="sd_device_enumerator_add_match_parent" xmlns:xi="http://www.w3.org/2001/XInclude">
+  <refentryinfo>
+    <title>sd_device_enumerator_add_match_parent</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>sd_device_enumerator_add_match_parent</refentrytitle>
+    <manvolnum>3</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>sd_device_enumerator_add_match_parent</refname>
+    <refname>sd_device_enumerator_add_match_property</refname>
+    <refname>sd_device_enumerator_add_match_property_required</refname>
+    <refname>sd_device_enumerator_add_match_subsystem</refname>
+    <refname>sd_device_enumerator_add_match_sysattr</refname>
+    <refname>sd_device_enumerator_add_match_sysname</refname>
+    <refname>sd_device_enumerator_add_nomatch_sysname</refname>
+    <refname>sd_device_enumerator_add_match_tag</refname>
+    <refname>sd_device_enumerator_allow_uninitialized</refname>
+    <refname>sd_device_enumerator_add_all_parents</refname>
+    <refpurpose>Add a filter to the device enumerator</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <funcsynopsis>
+    <funcsynopsisinfo>#include &lt;systemd/sd-device.h&gt;</funcsynopsisinfo>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_add_match_parent</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+      <paramdef>sd_device *<parameter>parent</parameter></paramdef>
+    </funcprototype>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_add_match_property</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+      <paramdef>const char *<parameter>property</parameter></paramdef>
+      <paramdef>const char *<parameter>value</parameter></paramdef>
+    </funcprototype>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_add_match_property_required</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+      <paramdef>const char *<parameter>property</parameter></paramdef>
+      <paramdef>const char *<parameter>value</parameter></paramdef>
+    </funcprototype>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_add_match_subsystem</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+      <paramdef>const char *<parameter>subsystem</parameter></paramdef>
+      <paramdef>int <parameter>match</parameter></paramdef>
+    </funcprototype>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_add_match_sysattr</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+      <paramdef>const char *<parameter>sysattr</parameter></paramdef>
+      <paramdef>const char *<parameter>value</parameter></paramdef>
+      <paramdef>int <parameter>match</parameter></paramdef>
+    </funcprototype>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_add_match_sysname</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+      <paramdef>const char *<parameter>sysname</parameter></paramdef>
+    </funcprototype>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_add_nomatch_sysname</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+      <paramdef>const char *<parameter>sysname</parameter></paramdef>
+    </funcprototype>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_add_match_tag</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+      <paramdef>const char *<parameter>tag</parameter></paramdef>
+    </funcprototype>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_allow_uninitialized</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+    </funcprototype>
+
+    <funcprototype>
+      <funcdef>int <function>sd_device_enumerator_add_all_parents</function></funcdef>
+      <paramdef>sd_device_enumerator *<parameter>enumerator</parameter></paramdef>
+    </funcprototype>
+
+    </funcsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>The <function>sd_device_enumerator_add_match_parent()</function> function adds a filter to
+    the <parameter>enumerator</parameter> so that only devices under the tree of the specified
+    <parameter>parent</parameter> device are enumerated. If this is called multiple times the
+    previously set <parameter>parent</parameter> device is cleared and only the last call takes an
+    effect.</para>
+
+    <para>The <function>sd_device_enumerator_add_match_property()</function> function adds a filter to
+    the <parameter>enumerator</parameter> so that only devices with the specified
+    <parameter>property</parameter> equals to the <parameter>value</parameter> are enumerated.
+    Both <parameter>property</parameter> and <parameter>value</parameter> can be a glob pattern.
+    When this is called multiple times, devices that have at least one of the specified
+    properties with matching values are enumerated. That is, filters are ORed.</para>
+
+    <para>The <function>sd_device_enumerator_add_match_property_required()</function> function adds a
+    filter to the <parameter>enumerator</parameter> so that only devices with the specified
+    <parameter>property</parameter> equals to the <parameter>value</parameter> are enumerated.
+    This function is similar to <function>sd_device_enumerator_add_match_property()</function>, but when
+    this is called multiple times, devices that have <emphasis>all</emphasis> specified properties
+    with matching values are enumerated. That is, filters are ANDed.</para>
+
+    <para>The <function>sd_device_enumerator_add_match_subsystem()</function> function adds a filter
+    to the <parameter>enumerator</parameter> so that all devices in the specified
+    <parameter>subsystem</parameter>, when <parameter>match</parameter> is <constant>true</constant>.
+    When <parameter>match</parameter> is <constant>false</constant>, then all devices except those in
+    the specified <parameter>subsystem</parameter> are enumerated. When called multiple times,
+    positive filters are ORed, and negative ones are ANDed.</para>
+
+    <para>The <function>sd_device_enumerator_add_match_sysattr()</function> function adds a filter on
+    the sysfs attribute <parameter>sysattr</parameter> matching <parameter>value</parameter>.
+    <parameter>value</parameter> can be a glob pattern. If <parameter>value</parameter> is
+    <constant>NULL</constant>, devices that either have (if <parameter>match</parameter>
+    is <constant>true</constant>) or do not have (if <parameter>match</parameter> is
+    <constant>false</constant>) the specified <parameter>sysattr</parameter> are included, regardless
+    of its value. That is, <constant>NULL</constant> is mostly equivalent to <literal>*</literal>.
+    When this function is called multiple times, only devices that match all specified
+    <parameter>sysattr</parameter> filters are enumerated. That is, these filters are ANDed.</para>
+
+    <para>The <function>sd_device_enumerator_add_match_sysname()</function> function adds a filter so
+    that only devices whose sysname equals to <parameter>sysname</parameter> are enumerated.
+    <parameter>sysname</parameter> can be a glob pattern. When called multiple times, filters are ORed.</para>
+
+    <para>The <function>sd_device_enumerator_add_nomatch_sysname()</function> function adds a filter
+    so that devices whose sysname equals to <parameter>sysname</parameter> are excluded from the
+    enumeration. This is useful for excluding specific devices from the enumeration process.
+    When called multiple times, features are ANDed.</para>
+
+    <para>The <function>sd_device_enumerator_add_match_tag()</function> function adds a filter so that
+    only devices tagged with <parameter>tag</parameter> are enumerated. When called multiple times,
+    filters are ORed.</para>
+
+    <para>The <function>sd_device_enumerator_allow_uninitialized()</function> function allows devices
+    that have not yet been initialized by udev to be included in the enumeration.</para>
+
+    <para>The <function>sd_device_enumerator_add_all_parents()</function> function enumerates all parent
+    devices of the matching devices. This is useful for cases where you want to include all parent
+    devices in the enumeration, such as when you are interested in the entire device tree leading up
+    to a specific device.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Return Value</title>
+
+    <para>All functions return <constant>0</constant> or a positive integer on success, or a negative
+    errno-style error code on failure.</para>
+
+    <refsect2>
+    <title>Errors</title>
+
+    <para>Returned errors may indicate the following problems:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><constant>-ENOMEM</constant></term>
+
+        <listitem><para>Memory allocation failed.</para></listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><constant>-EINVAL</constant></term>
+
+        <listitem><para>One of the arguments is invalid.</para></listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect2>
+  </refsect1>
+
+  <refsect1>
+  <title>Examples</title>
+
+  <example>
+    <title>Detect Removable USB Devices (Using Match and Exclude)</title>
+    <programlisting><xi:include href="sd_device_enumerator_add_match_parent-example.c" parse="text"/></programlisting>
+  </example>
+  </refsect1>
+
+  <refsect1>
+    <title>History</title>
+    <para><function>sd_device_enumerator_add_match_parent()</function>,
+    <function>sd_device_enumerator_add_match_property()</function>,
+    <function>sd_device_enumerator_add_match_subsystem()</function>,
+    <function>sd_device_enumerator_add_match_sysattr()</function>,
+    <function>sd_device_enumerator_add_match_sysname()</function>,
+    <function>sd_device_enumerator_add_match_tag()</function>, and
+    <function>sd_device_enumerator_allow_uninitialized()</function> were added in version 240.</para>
+
+    <para><function>sd_device_enumerator_add_nomatch_sysname()</function> was added in version 251.</para>
+
+    <para><function>sd_device_enumerator_add_match_property_required()</function> was added in version 255.</para>
+
+    <para><function>sd_device_enumerator_add_all_parents()</function> was added in version 258.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>sd_device_ref</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>sd_device_enumerator_new</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>sd_device_enumerator_get_device_first</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
+    </simplelist></para>
+  </refsect1>
+</refentry>