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 struct udev_enumerate
*udev_enumerate
;
56 r
= sd_device_enumerator_new(&e
);
58 return_with_errno(NULL
, r
);
60 r
= sd_device_enumerator_allow_uninitialized(e
);
62 return_with_errno(NULL
, r
);
64 udev_enumerate
= new(struct udev_enumerate
, 1);
66 return_with_errno(NULL
, ENOMEM
);
68 *udev_enumerate
= (struct udev_enumerate
) {
71 .enumerator
= TAKE_PTR(e
),
74 udev_list_init(&udev_enumerate
->devices_list
, false);
76 return udev_enumerate
;
79 static struct udev_enumerate
*udev_enumerate_free(struct udev_enumerate
*udev_enumerate
) {
80 assert(udev_enumerate
);
82 udev_list_cleanup(&udev_enumerate
->devices_list
);
83 sd_device_enumerator_unref(udev_enumerate
->enumerator
);
84 return mfree(udev_enumerate
);
89 * @udev_enumerate: context
91 * Take a reference of a enumeration context.
93 * Returns: the passed enumeration context
97 * udev_enumerate_unref:
98 * @udev_enumerate: context
100 * Drop a reference of an enumeration context. If the refcount reaches zero,
101 * all resources of the enumeration context will be released.
105 DEFINE_PUBLIC_TRIVIAL_REF_UNREF_FUNC(struct udev_enumerate
, udev_enumerate
, udev_enumerate_free
);
108 * udev_enumerate_get_udev:
109 * @udev_enumerate: context
111 * Get the udev library context.
113 * Returns: a pointer to the context.
115 _public_
struct udev
*udev_enumerate_get_udev(struct udev_enumerate
*udev_enumerate
) {
116 assert_return_errno(udev_enumerate
, NULL
, EINVAL
);
118 return udev_enumerate
->udev
;
122 * udev_enumerate_get_list_entry:
123 * @udev_enumerate: context
125 * Get the first entry of the sorted list of device paths.
127 * Returns: a udev_list_entry.
129 _public_
struct udev_list_entry
*udev_enumerate_get_list_entry(struct udev_enumerate
*udev_enumerate
) {
130 struct udev_list_entry
*e
;
132 assert_return_errno(udev_enumerate
, NULL
, EINVAL
);
134 if (!udev_enumerate
->devices_uptodate
) {
137 udev_list_cleanup(&udev_enumerate
->devices_list
);
139 FOREACH_DEVICE_AND_SUBSYSTEM(udev_enumerate
->enumerator
, device
) {
143 r
= sd_device_get_syspath(device
, &syspath
);
145 return_with_errno(NULL
, r
);
147 if (!udev_list_entry_add(&udev_enumerate
->devices_list
, syspath
, NULL
))
148 return_with_errno(NULL
, ENOMEM
);
151 udev_enumerate
->devices_uptodate
= true;
154 e
= udev_list_get_entry(&udev_enumerate
->devices_list
);
156 return_with_errno(NULL
, ENODATA
);
162 * udev_enumerate_add_match_subsystem:
163 * @udev_enumerate: context
164 * @subsystem: filter for a subsystem of the device to include in the list
166 * Match only devices belonging to a certain kernel subsystem.
168 * Returns: 0 on success, otherwise a negative error value.
170 _public_
int udev_enumerate_add_match_subsystem(struct udev_enumerate
*udev_enumerate
, const char *subsystem
) {
171 assert_return(udev_enumerate
, -EINVAL
);
176 return sd_device_enumerator_add_match_subsystem(udev_enumerate
->enumerator
, subsystem
, true);
180 * udev_enumerate_add_nomatch_subsystem:
181 * @udev_enumerate: context
182 * @subsystem: filter for a subsystem of the device to exclude from the list
184 * Match only devices not belonging to a certain kernel subsystem.
186 * Returns: 0 on success, otherwise a negative error value.
188 _public_
int udev_enumerate_add_nomatch_subsystem(struct udev_enumerate
*udev_enumerate
, const char *subsystem
) {
189 assert_return(udev_enumerate
, -EINVAL
);
194 return sd_device_enumerator_add_match_subsystem(udev_enumerate
->enumerator
, subsystem
, false);
198 * udev_enumerate_add_match_sysattr:
199 * @udev_enumerate: context
200 * @sysattr: filter for a sys attribute at the device to include in the list
201 * @value: optional value of the sys attribute
203 * Match only devices with a certain /sys device attribute.
205 * Returns: 0 on success, otherwise a negative error value.
207 _public_
int udev_enumerate_add_match_sysattr(struct udev_enumerate
*udev_enumerate
, const char *sysattr
, const char *value
) {
208 assert_return(udev_enumerate
, -EINVAL
);
213 return sd_device_enumerator_add_match_sysattr(udev_enumerate
->enumerator
, sysattr
, value
, true);
217 * udev_enumerate_add_nomatch_sysattr:
218 * @udev_enumerate: context
219 * @sysattr: filter for a sys attribute at the device to exclude from the list
220 * @value: optional value of the sys attribute
222 * Match only devices not having a certain /sys device attribute.
224 * Returns: 0 on success, otherwise a negative error value.
226 _public_
int udev_enumerate_add_nomatch_sysattr(struct udev_enumerate
*udev_enumerate
, const char *sysattr
, const char *value
) {
227 assert_return(udev_enumerate
, -EINVAL
);
232 return sd_device_enumerator_add_match_sysattr(udev_enumerate
->enumerator
, sysattr
, value
, false);
236 * udev_enumerate_add_match_property:
237 * @udev_enumerate: context
238 * @property: filter for a property of the device to include in the list
239 * @value: value of the property
241 * Match only devices with a certain property.
243 * Returns: 0 on success, otherwise a negative error value.
245 _public_
int udev_enumerate_add_match_property(struct udev_enumerate
*udev_enumerate
, const char *property
, const char *value
) {
246 assert_return(udev_enumerate
, -EINVAL
);
251 return sd_device_enumerator_add_match_property(udev_enumerate
->enumerator
, property
, value
);
255 * udev_enumerate_add_match_tag:
256 * @udev_enumerate: context
257 * @tag: filter for a tag of the device to include in the list
259 * Match only devices with a certain tag.
261 * Returns: 0 on success, otherwise a negative error value.
263 _public_
int udev_enumerate_add_match_tag(struct udev_enumerate
*udev_enumerate
, const char *tag
) {
264 assert_return(udev_enumerate
, -EINVAL
);
269 return sd_device_enumerator_add_match_tag(udev_enumerate
->enumerator
, tag
);
273 * udev_enumerate_add_match_parent:
274 * @udev_enumerate: context
275 * @parent: parent device where to start searching
277 * Return the devices on the subtree of one given device. The parent
278 * itself is included in the list.
280 * A reference for the device is held until the udev_enumerate context
283 * Returns: 0 on success, otherwise a negative error value.
285 _public_
int udev_enumerate_add_match_parent(struct udev_enumerate
*udev_enumerate
, struct udev_device
*parent
) {
286 assert_return(udev_enumerate
, -EINVAL
);
291 return sd_device_enumerator_add_match_parent(udev_enumerate
->enumerator
, parent
->device
);
295 * udev_enumerate_add_match_is_initialized:
296 * @udev_enumerate: context
298 * Match only devices which udev has set up already. This makes
299 * sure, that the device node permissions and context are properly set
300 * and that network devices are fully renamed.
302 * Usually, devices which are found in the kernel but not already
303 * handled by udev, have still pending events. Services should subscribe
304 * to monitor events and wait for these devices to become ready, instead
305 * of using uninitialized devices.
307 * For now, this will not affect devices which do not have a device node
308 * and are not network interfaces.
310 * Returns: 0 on success, otherwise a negative error value.
312 _public_
int udev_enumerate_add_match_is_initialized(struct udev_enumerate
*udev_enumerate
) {
313 assert_return(udev_enumerate
, -EINVAL
);
315 return device_enumerator_add_match_is_initialized(udev_enumerate
->enumerator
);
319 * udev_enumerate_add_match_sysname:
320 * @udev_enumerate: context
321 * @sysname: filter for the name of the device to include in the list
323 * Match only devices with a given /sys device name.
325 * Returns: 0 on success, otherwise a negative error value.
327 _public_
int udev_enumerate_add_match_sysname(struct udev_enumerate
*udev_enumerate
, const char *sysname
) {
328 assert_return(udev_enumerate
, -EINVAL
);
333 return sd_device_enumerator_add_match_sysname(udev_enumerate
->enumerator
, sysname
);
337 * udev_enumerate_add_syspath:
338 * @udev_enumerate: context
339 * @syspath: path of a device
341 * Add a device to the list of devices, to retrieve it back sorted in dependency order.
343 * Returns: 0 on success, otherwise a negative error value.
345 _public_
int udev_enumerate_add_syspath(struct udev_enumerate
*udev_enumerate
, const char *syspath
) {
346 _cleanup_(sd_device_unrefp
) sd_device
*device
= NULL
;
349 assert_return(udev_enumerate
, -EINVAL
);
354 r
= sd_device_new_from_syspath(&device
, syspath
);
358 r
= device_enumerator_add_device(udev_enumerate
->enumerator
, device
);
366 * udev_enumerate_scan_devices:
367 * @udev_enumerate: udev enumeration context
369 * Scan /sys for all devices which match the given filters. No matches
370 * will return all currently available devices.
372 * Returns: 0 on success, otherwise a negative error value.
374 _public_
int udev_enumerate_scan_devices(struct udev_enumerate
*udev_enumerate
) {
375 assert_return(udev_enumerate
, -EINVAL
);
377 return device_enumerator_scan_devices(udev_enumerate
->enumerator
);
381 * udev_enumerate_scan_subsystems:
382 * @udev_enumerate: udev enumeration context
384 * Scan /sys for all kernel subsystems, including buses, classes, drivers.
386 * Returns: 0 on success, otherwise a negative error value.
388 _public_
int udev_enumerate_scan_subsystems(struct udev_enumerate
*udev_enumerate
) {
389 assert_return(udev_enumerate
, -EINVAL
);
391 return device_enumerator_scan_subsystems(udev_enumerate
->enumerator
);