Debian Codegraph @

upstream/debian-unstable/man3/sd_device_enumerator_add_match_parent.3

raw
1 '\" t
2 .TH "SD_DEVICE_ENUMERATOR_ADD_MATCH_PARENT" "3" "" "systemd 261~rc3" "sd_device_enumerator_add_match_parent"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 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_nomatch_sysname, sd_device_enumerator_add_match_tag, sd_device_enumerator_allow_uninitialized, sd_device_enumerator_add_all_parents \- Add a filter to the device enumerator
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-device\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_device_enumerator_add_match_parent('u
32 .BI "int sd_device_enumerator_add_match_parent(sd_device_enumerator\ *" "enumerator" ", sd_device\ *" "parent" ");"
33 .HP \w'int\ sd_device_enumerator_add_match_property('u
34 .BI "int sd_device_enumerator_add_match_property(sd_device_enumerator\ *" "enumerator" ", const\ char\ *" "property" ", const\ char\ *" "value" ");"
35 .HP \w'int\ sd_device_enumerator_add_match_property_required('u
36 .BI "int sd_device_enumerator_add_match_property_required(sd_device_enumerator\ *" "enumerator" ", const\ char\ *" "property" ", const\ char\ *" "value" ");"
37 .HP \w'int\ sd_device_enumerator_add_match_subsystem('u
38 .BI "int sd_device_enumerator_add_match_subsystem(sd_device_enumerator\ *" "enumerator" ", const\ char\ *" "subsystem" ", int\ " "match" ");"
39 .HP \w'int\ sd_device_enumerator_add_match_sysattr('u
40 .BI "int sd_device_enumerator_add_match_sysattr(sd_device_enumerator\ *" "enumerator" ", const\ char\ *" "sysattr" ", const\ char\ *" "value" ", int\ " "match" ");"
41 .HP \w'int\ sd_device_enumerator_add_match_sysname('u
42 .BI "int sd_device_enumerator_add_match_sysname(sd_device_enumerator\ *" "enumerator" ", const\ char\ *" "sysname" ");"
43 .HP \w'int\ sd_device_enumerator_add_nomatch_sysname('u
44 .BI "int sd_device_enumerator_add_nomatch_sysname(sd_device_enumerator\ *" "enumerator" ", const\ char\ *" "sysname" ");"
45 .HP \w'int\ sd_device_enumerator_add_match_tag('u
46 .BI "int sd_device_enumerator_add_match_tag(sd_device_enumerator\ *" "enumerator" ", const\ char\ *" "tag" ");"
47 .HP \w'int\ sd_device_enumerator_allow_uninitialized('u
48 .BI "int sd_device_enumerator_allow_uninitialized(sd_device_enumerator\ *" "enumerator" ");"
49 .HP \w'int\ sd_device_enumerator_add_all_parents('u
50 .BI "int sd_device_enumerator_add_all_parents(sd_device_enumerator\ *" "enumerator" ");"
51 .SH "DESCRIPTION"
52 .PP
53 The
54 \fBsd_device_enumerator_add_match_parent()\fR
55 function adds a filter to the
56 \fIenumerator\fR
57 so that only devices under the tree of the specified
58 \fIparent\fR
59 device are enumerated\&. If this is called multiple times the previously set
60 \fIparent\fR
61 device is cleared and only the last call takes an effect\&.
62 .PP
63 The
64 \fBsd_device_enumerator_add_match_property()\fR
65 function adds a filter to the
66 \fIenumerator\fR
67 so that only devices with the specified
68 \fIproperty\fR
69 equals to the
70 \fIvalue\fR
71 are enumerated\&. Both
72 \fIproperty\fR
73 and
74 \fIvalue\fR
75 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\&.
76 .PP
77 The
78 \fBsd_device_enumerator_add_match_property_required()\fR
79 function adds a filter to the
80 \fIenumerator\fR
81 so that only devices with the specified
82 \fIproperty\fR
83 equals to the
84 \fIvalue\fR
85 are enumerated\&. This function is similar to
86 \fBsd_device_enumerator_add_match_property()\fR, but when this is called multiple times, devices that have
87 \fIall\fR
88 specified properties with matching values are enumerated\&. That is, filters are ANDed\&.
89 .PP
90 The
91 \fBsd_device_enumerator_add_match_subsystem()\fR
92 function adds a filter to the
93 \fIenumerator\fR
94 so that all devices in the specified
95 \fIsubsystem\fR, when
96 \fImatch\fR
97 is
98 \fBtrue\fR\&. When
99 \fImatch\fR
100 is
101 \fBfalse\fR, then all devices except those in the specified
102 \fIsubsystem\fR
103 are enumerated\&. When called multiple times, positive filters are ORed, and negative ones are ANDed\&.
104 .PP
105 The
106 \fBsd_device_enumerator_add_match_sysattr()\fR
107 function adds a filter on the sysfs attribute
108 \fIsysattr\fR
109 matching
110 \fIvalue\fR\&.
111 \fIvalue\fR
112 can be a glob pattern\&. If
113 \fIvalue\fR
114 is
115 \fBNULL\fR, devices that either have (if
116 \fImatch\fR
117 is
118 \fBtrue\fR) or do not have (if
119 \fImatch\fR
120 is
121 \fBfalse\fR) the specified
122 \fIsysattr\fR
123 are included, regardless of its value\&. That is,
124 \fBNULL\fR
125 is mostly equivalent to
126 "*"\&. When this function is called multiple times, only devices that match all specified
127 \fIsysattr\fR
128 filters are enumerated\&. That is, these filters are ANDed\&.
129 .PP
130 The
131 \fBsd_device_enumerator_add_match_sysname()\fR
132 function adds a filter so that only devices whose sysname equals to
133 \fIsysname\fR
134 are enumerated\&.
135 \fIsysname\fR
136 can be a glob pattern\&. When called multiple times, filters are ORed\&.
137 .PP
138 The
139 \fBsd_device_enumerator_add_nomatch_sysname()\fR
140 function adds a filter so that devices whose sysname equals to
141 \fIsysname\fR
142 are excluded from the enumeration\&. This is useful for excluding specific devices from the enumeration process\&. When called multiple times, features are ANDed\&.
143 .PP
144 The
145 \fBsd_device_enumerator_add_match_tag()\fR
146 function adds a filter so that only devices tagged with
147 \fItag\fR
148 are enumerated\&. When called multiple times, filters are ORed\&.
149 .PP
150 The
151 \fBsd_device_enumerator_allow_uninitialized()\fR
152 function allows devices that have not yet been initialized by udev to be included in the enumeration\&.
153 .PP
154 The
155 \fBsd_device_enumerator_add_all_parents()\fR
156 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\&.
157 .SH "RETURN VALUE"
158 .PP
159 All functions return
160 \fB0\fR
161 or a positive integer on success, or a negative errno\-style error code on failure\&.
162 .SS "Errors"
163 .PP
164 Returned errors may indicate the following problems:
165 .PP
166 \fB\-ENOMEM\fR
167 .RS 4
168 Memory allocation failed\&.
169 .RE
170 .PP
171 \fB\-EINVAL\fR
172 .RS 4
173 One of the arguments is invalid\&.
174 .RE
175 .SH "EXAMPLES"
176 .PP
177 \fBExample\ \&1.\ \&Detect Removable USB Devices (Using Match and Exclude)\fR
178 .sp
179 .if n \{\
180 .RS 4
181 .\}
182 .nf
183 /* SPDX\-License\-Identifier: MIT\-0 */
184
185 #include <stdbool\&.h>
186 #include <stdio\&.h>
187 #include <systemd/sd\-device\&.h>
188
189 int main(void) {
190 __attribute__((cleanup(sd_device_enumerator_unrefp))) sd_device_enumerator *enumerator = NULL;
191 sd_device *device;
192 int r;
193
194 /* Create a new device enumerator */
195 r = sd_device_enumerator_new(&enumerator);
196 if (r < 0) {
197 fprintf(stderr, "Failed to create device enumerator: %s\en", strerror(\-r));
198 return 1;
199 }
200
201 /* Include only devices from the "usb" subsystem */
202 r = sd_device_enumerator_add_match_subsystem(enumerator, "usb", true);
203 if (r < 0) {
204 fprintf(stderr, "Failed to add subsystem match: %s\en", strerror(\-r));
205 return 1;
206 }
207
208 /*
209 * Exclude devices where the "removable" sysattr is "0"
210 * These are typically non\-removable devices like built\-in USB interfaces
211 */
212 r = sd_device_enumerator_add_match_sysattr(enumerator, "removable", "0", false);
213 if (r < 0) {
214 fprintf(stderr, "Failed to add sysattr match: %s\en", strerror(\-r));
215 return 1;
216 }
217
218 /* Begin enumerating matching devices */
219 for (device = sd_device_enumerator_get_device_first(enumerator);
220 device;
221 device = sd_device_enumerator_get_device_next(enumerator)) {
222 const char *syspath;
223
224 /* Get syspath for the device */
225 if (sd_device_get_syspath(device, &syspath) >= 0)
226 printf("Removable USB device found: %s\en", syspath);
227 }
228 return 0;
229 }
230 .fi
231 .if n \{\
232 .RE
233 .\}
234 .SH "HISTORY"
235 .PP
236 \fBsd_device_enumerator_add_match_parent()\fR,
237 \fBsd_device_enumerator_add_match_property()\fR,
238 \fBsd_device_enumerator_add_match_subsystem()\fR,
239 \fBsd_device_enumerator_add_match_sysattr()\fR,
240 \fBsd_device_enumerator_add_match_sysname()\fR,
241 \fBsd_device_enumerator_add_match_tag()\fR, and
242 \fBsd_device_enumerator_allow_uninitialized()\fR
243 were added in version 240\&.
244 .PP
245 \fBsd_device_enumerator_add_nomatch_sysname()\fR
246 was added in version 251\&.
247 .PP
248 \fBsd_device_enumerator_add_match_property_required()\fR
249 was added in version 255\&.
250 .PP
251 \fBsd_device_enumerator_add_all_parents()\fR
252 was added in version 258\&.
253 .SH "SEE ALSO"
254 .PP
255 \fBsd_device_ref\fR(3), \fBsd_device_enumerator_new\fR(3), \fBsd_device_enumerator_get_device_first\fR(3)