morgan/systemd
1
0
Fork 0
mirror of https://github.com/morgan9e/systemd synced 2026-04-14 00:14:32 +09:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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
This commit is contained in:
Shubhendra Kushwaha
2025-05-29 15:10:18 +05:30
committed by GitHub
parent 4313aeedf5
commit fbad1beae4
4 changed files with 283 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
man/meson.build
View File

@@ -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',

12
man/rules/meson.build
View File

@@ -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',

47
man/sd_device_enumerator_add_match_parent-example.c Normal file
View File

@@ -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;
}

223
man/sd_device_enumerator_add_match_parent.xml Normal file
View File

@@ -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>