1 /* SPDX-License-Identifier: LGPL-2.1+ */
14 #include "sd-device.h"
16 #include "alloc-util.h"
17 #include "device-enumerator-private.h"
18 #include "device-util.h"
19 #include "libudev-device-internal.h"
22 * SECTION:libudev-enumerate
23 * @short_description: lookup and sort sys devices
25 * Lookup devices in the sys filesystem, filter devices by properties,
26 * and return a sorted list of devices.
32 * Opaque object representing one device lookup/sort context.
34 struct udev_enumerate
{
37 struct udev_list
*devices_list
;
38 bool devices_uptodate
:1;
40 sd_device_enumerator
*enumerator
;
45 * @udev: udev library context
47 * Create an enumeration context to scan /sys.
49 * Returns: an enumeration context.
51 _public_
struct udev_enumerate
*udev_enumerate_new(struct udev
*udev
) {
52 _cleanup_(sd_device_enumerator_unrefp
) sd_device_enumerator
*e
= NULL
;
53 _cleanup_(udev_list_freep
) struct udev_list
*list
= NULL
;
54 struct udev_enumerate
*udev_enumerate
;
57 r
= sd_device_enumerator_new(&e
);
59 return_with_errno(NULL
, r
);
61 r
= sd_device_enumerator_allow_uninitialized(e
);
63 return_with_errno(NULL
, r
);
65 list
= udev_list_new(false);
67 return_with_errno(NULL
, ENOMEM
);
69 udev_enumerate
= new(struct udev_enumerate
, 1);
71 return_with_errno(NULL
, ENOMEM
);
73 *udev_enumerate
= (struct udev_enumerate
) {
76 .enumerator
= TAKE_PTR(e
),
77 .devices_list
= TAKE_PTR(list
),
80 return udev_enumerate
;
83 static struct udev_enumerate
*udev_enumerate_free(struct udev_enumerate
*udev_enumerate
) {
84 assert(udev_enumerate
);
86 udev_list_free(udev_enumerate
->devices_list
);
87 sd_device_enumerator_unref(udev_enumerate
->enumerator
);
88 return mfree(udev_enumerate
);
93 * @udev_enumerate: context
95 * Take a reference of a enumeration context.
97 * Returns: the passed enumeration context
101 * udev_enumerate_unref:
102 * @udev_enumerate: context
104 * Drop a reference of an enumeration context. If the refcount reaches zero,
105 * all resources of the enumeration context will be released.
109 DEFINE_PUBLIC_TRIVIAL_REF_UNREF_FUNC(struct udev_enumerate
, udev_enumerate
, udev_enumerate_free
);
112 * udev_enumerate_get_udev:
113 * @udev_enumerate: context
115 * Get the udev library context.
117 * Returns: a pointer to the context.
119 _public_
struct udev
*udev_enumerate_get_udev(struct udev_enumerate
*udev_enumerate
) {
120 assert_return_errno(udev_enumerate
, NULL
, EINVAL
);
122 return udev_enumerate
->udev
;
126 * udev_enumerate_get_list_entry:
127 * @udev_enumerate: context
129 * Get the first entry of the sorted list of device paths.
131 * Returns: a udev_list_entry.
133 _public_
struct udev_list_entry
*udev_enumerate_get_list_entry(struct udev_enumerate
*udev_enumerate
) {
134 struct udev_list_entry
*e
;
136 assert_return_errno(udev_enumerate
, NULL
, EINVAL
);
138 if (!udev_enumerate
->devices_uptodate
) {
141 udev_list_cleanup(udev_enumerate
->devices_list
);
143 FOREACH_DEVICE_AND_SUBSYSTEM(udev_enumerate
->enumerator
, device
) {
147 r
= sd_device_get_syspath(device
, &syspath
);
149 return_with_errno(NULL
, r
);
151 if (!udev_list_entry_add(udev_enumerate
->devices_list
, syspath
, NULL
))
152 return_with_errno(NULL
, ENOMEM
);
155 udev_enumerate
->devices_uptodate
= true;
158 e
= udev_list_get_entry(udev_enumerate
->devices_list
);
160 return_with_errno(NULL
, ENODATA
);
166 * udev_enumerate_add_match_subsystem:
167 * @udev_enumerate: context
168 * @subsystem: filter for a subsystem of the device to include in the list
170 * Match only devices belonging to a certain kernel subsystem.
172 * Returns: 0 on success, otherwise a negative error value.
174 _public_
int udev_enumerate_add_match_subsystem(struct udev_enumerate
*udev_enumerate
, const char *subsystem
) {
175 assert_return(udev_enumerate
, -EINVAL
);
180 return sd_device_enumerator_add_match_subsystem(udev_enumerate
->enumerator
, subsystem
, true);
184 * udev_enumerate_add_nomatch_subsystem:
185 * @udev_enumerate: context
186 * @subsystem: filter for a subsystem of the device to exclude from the list
188 * Match only devices not belonging to a certain kernel subsystem.
190 * Returns: 0 on success, otherwise a negative error value.
192 _public_
int udev_enumerate_add_nomatch_subsystem(struct udev_enumerate
*udev_enumerate
, const char *subsystem
) {
193 assert_return(udev_enumerate
, -EINVAL
);
198 return sd_device_enumerator_add_match_subsystem(udev_enumerate
->enumerator
, subsystem
, false);
202 * udev_enumerate_add_match_sysattr:
203 * @udev_enumerate: context
204 * @sysattr: filter for a sys attribute at the device to include in the list
205 * @value: optional value of the sys attribute
207 * Match only devices with a certain /sys device attribute.
209 * Returns: 0 on success, otherwise a negative error value.
211 _public_
int udev_enumerate_add_match_sysattr(struct udev_enumerate
*udev_enumerate
, const char *sysattr
, const char *value
) {
212 assert_return(udev_enumerate
, -EINVAL
);
217 return sd_device_enumerator_add_match_sysattr(udev_enumerate
->enumerator
, sysattr
, value
, true);
221 * udev_enumerate_add_nomatch_sysattr:
222 * @udev_enumerate: context
223 * @sysattr: filter for a sys attribute at the device to exclude from the list
224 * @value: optional value of the sys attribute
226 * Match only devices not having a certain /sys device attribute.
228 * Returns: 0 on success, otherwise a negative error value.
230 _public_
int udev_enumerate_add_nomatch_sysattr(struct udev_enumerate
*udev_enumerate
, const char *sysattr
, const char *value
) {
231 assert_return(udev_enumerate
, -EINVAL
);
236 return sd_device_enumerator_add_match_sysattr(udev_enumerate
->enumerator
, sysattr
, value
, false);
240 * udev_enumerate_add_match_property:
241 * @udev_enumerate: context
242 * @property: filter for a property of the device to include in the list
243 * @value: value of the property
245 * Match only devices with a certain property.
247 * Returns: 0 on success, otherwise a negative error value.
249 _public_
int udev_enumerate_add_match_property(struct udev_enumerate
*udev_enumerate
, const char *property
, const char *value
) {
250 assert_return(udev_enumerate
, -EINVAL
);
255 return sd_device_enumerator_add_match_property(udev_enumerate
->enumerator
, property
, value
);
259 * udev_enumerate_add_match_tag:
260 * @udev_enumerate: context
261 * @tag: filter for a tag of the device to include in the list
263 * Match only devices with a certain tag.
265 * Returns: 0 on success, otherwise a negative error value.
267 _public_
int udev_enumerate_add_match_tag(struct udev_enumerate
*udev_enumerate
, const char *tag
) {
268 assert_return(udev_enumerate
, -EINVAL
);
273 return sd_device_enumerator_add_match_tag(udev_enumerate
->enumerator
, tag
);
277 * udev_enumerate_add_match_parent:
278 * @udev_enumerate: context
279 * @parent: parent device where to start searching
281 * Return the devices on the subtree of one given device. The parent
282 * itself is included in the list.
284 * Returns: 0 on success, otherwise a negative error value.
286 _public_
int udev_enumerate_add_match_parent(struct udev_enumerate
*udev_enumerate
, struct udev_device
*parent
) {
287 assert_return(udev_enumerate
, -EINVAL
);
292 return sd_device_enumerator_add_match_parent(udev_enumerate
->enumerator
, parent
->device
);
296 * udev_enumerate_add_match_is_initialized:
297 * @udev_enumerate: context
299 * Match only devices which udev has set up already. This makes
300 * sure, that the device node permissions and context are properly set
301 * and that network devices are fully renamed.
303 * Usually, devices which are found in the kernel but not already
304 * handled by udev, have still pending events. Services should subscribe
305 * to monitor events and wait for these devices to become ready, instead
306 * of using uninitialized devices.
308 * For now, this will not affect devices which do not have a device node
309 * and are not network interfaces.
311 * Returns: 0 on success, otherwise a negative error value.
313 _public_
int udev_enumerate_add_match_is_initialized(struct udev_enumerate
*udev_enumerate
) {
314 assert_return(udev_enumerate
, -EINVAL
);
316 return device_enumerator_add_match_is_initialized(udev_enumerate
->enumerator
);
320 * udev_enumerate_add_match_sysname:
321 * @udev_enumerate: context
322 * @sysname: filter for the name of the device to include in the list
324 * Match only devices with a given /sys device name.
326 * Returns: 0 on success, otherwise a negative error value.
328 _public_
int udev_enumerate_add_match_sysname(struct udev_enumerate
*udev_enumerate
, const char *sysname
) {
329 assert_return(udev_enumerate
, -EINVAL
);
334 return sd_device_enumerator_add_match_sysname(udev_enumerate
->enumerator
, sysname
);
338 * udev_enumerate_add_syspath:
339 * @udev_enumerate: context
340 * @syspath: path of a device
342 * Add a device to the list of devices, to retrieve it back sorted in dependency order.
344 * Returns: 0 on success, otherwise a negative error value.
346 _public_
int udev_enumerate_add_syspath(struct udev_enumerate
*udev_enumerate
, const char *syspath
) {
347 _cleanup_(sd_device_unrefp
) sd_device
*device
= NULL
;
350 assert_return(udev_enumerate
, -EINVAL
);
355 r
= sd_device_new_from_syspath(&device
, syspath
);
359 r
= device_enumerator_add_device(udev_enumerate
->enumerator
, device
);
367 * udev_enumerate_scan_devices:
368 * @udev_enumerate: udev enumeration context
370 * Scan /sys for all devices which match the given filters. No matches
371 * will return all currently available devices.
373 * Returns: 0 on success, otherwise a negative error value.
375 _public_
int udev_enumerate_scan_devices(struct udev_enumerate
*udev_enumerate
) {
376 assert_return(udev_enumerate
, -EINVAL
);
378 return device_enumerator_scan_devices(udev_enumerate
->enumerator
);
382 * udev_enumerate_scan_subsystems:
383 * @udev_enumerate: udev enumeration context
385 * Scan /sys for all kernel subsystems, including buses, classes, drivers.
387 * Returns: 0 on success, otherwise a negative error value.
389 _public_
int udev_enumerate_scan_subsystems(struct udev_enumerate
*udev_enumerate
) {
390 assert_return(udev_enumerate
, -EINVAL
);
392 return device_enumerator_scan_subsystems(udev_enumerate
->enumerator
);