]>
git.ipfire.org Git - thirdparty/systemd.git/blob - src/libudev/libudev-enumerate.c
1 /* SPDX-License-Identifier: LGPL-2.1+ */
3 This file is part of systemd.
5 Copyright 2008-2012 Kay Sievers <kay@vrfy.org>
6 Copyright 2015 Tom Gundersen <teg@jklm.no>
8 systemd is free software; you can redistribute it and/or modify it
9 under the terms of the GNU Lesser General Public License as published by
10 the Free Software Foundation; either version 2.1 of the License, or
11 (at your option) any later version.
13 systemd is distributed in the hope that it will be useful, but
14 WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
18 You should have received a copy of the GNU Lesser General Public License
19 along with systemd; If not, see <http://www.gnu.org/licenses/>.
33 #include "sd-device.h"
35 #include "alloc-util.h"
36 #include "device-enumerator-private.h"
37 #include "device-util.h"
38 #include "libudev-device-internal.h"
41 * SECTION:libudev-enumerate
42 * @short_description: lookup and sort sys devices
44 * Lookup devices in the sys filesystem, filter devices by properties,
45 * and return a sorted list of devices.
51 * Opaque object representing one device lookup/sort context.
53 struct udev_enumerate
{
56 struct udev_list devices_list
;
57 bool devices_uptodate
:1;
59 sd_device_enumerator
*enumerator
;
64 * @udev: udev library context
66 * Create an enumeration context to scan /sys.
68 * Returns: an enumeration context.
70 _public_
struct udev_enumerate
*udev_enumerate_new(struct udev
*udev
) {
71 _cleanup_free_
struct udev_enumerate
*udev_enumerate
= NULL
;
74 assert_return_errno(udev
, NULL
, EINVAL
);
76 udev_enumerate
= new0(struct udev_enumerate
, 1);
77 if (!udev_enumerate
) {
82 r
= sd_device_enumerator_new(&udev_enumerate
->enumerator
);
88 r
= sd_device_enumerator_allow_uninitialized(udev_enumerate
->enumerator
);
94 udev_enumerate
->refcount
= 1;
95 udev_enumerate
->udev
= udev
;
97 udev_list_init(udev
, &udev_enumerate
->devices_list
, false);
99 return TAKE_PTR(udev_enumerate
);
103 * udev_enumerate_ref:
104 * @udev_enumerate: context
106 * Take a reference of a enumeration context.
108 * Returns: the passed enumeration context
110 _public_
struct udev_enumerate
*udev_enumerate_ref(struct udev_enumerate
*udev_enumerate
) {
112 udev_enumerate
->refcount
++;
114 return udev_enumerate
;
118 * udev_enumerate_unref:
119 * @udev_enumerate: context
121 * Drop a reference of an enumeration context. If the refcount reaches zero,
122 * all resources of the enumeration context will be released.
126 _public_
struct udev_enumerate
*udev_enumerate_unref(struct udev_enumerate
*udev_enumerate
) {
127 if (udev_enumerate
&& (-- udev_enumerate
->refcount
) == 0) {
128 udev_list_cleanup(&udev_enumerate
->devices_list
);
129 sd_device_enumerator_unref(udev_enumerate
->enumerator
);
130 free(udev_enumerate
);
137 * udev_enumerate_get_udev:
138 * @udev_enumerate: context
140 * Get the udev library context.
142 * Returns: a pointer to the context.
144 _public_
struct udev
*udev_enumerate_get_udev(struct udev_enumerate
*udev_enumerate
) {
145 assert_return_errno(udev_enumerate
, NULL
, EINVAL
);
147 return udev_enumerate
->udev
;
151 * udev_enumerate_get_list_entry:
152 * @udev_enumerate: context
154 * Get the first entry of the sorted list of device paths.
156 * Returns: a udev_list_entry.
158 _public_
struct udev_list_entry
*udev_enumerate_get_list_entry(struct udev_enumerate
*udev_enumerate
) {
159 struct udev_list_entry
*e
;
161 assert_return_errno(udev_enumerate
, NULL
, EINVAL
);
163 if (!udev_enumerate
->devices_uptodate
) {
166 udev_list_cleanup(&udev_enumerate
->devices_list
);
168 FOREACH_DEVICE_AND_SUBSYSTEM(udev_enumerate
->enumerator
, device
) {
172 r
= sd_device_get_syspath(device
, &syspath
);
178 udev_list_entry_add(&udev_enumerate
->devices_list
, syspath
, NULL
);
181 udev_enumerate
->devices_uptodate
= true;
184 e
= udev_list_get_entry(&udev_enumerate
->devices_list
);
192 * udev_enumerate_add_match_subsystem:
193 * @udev_enumerate: context
194 * @subsystem: filter for a subsystem of the device to include in the list
196 * Match only devices belonging to a certain kernel subsystem.
198 * Returns: 0 on success, otherwise a negative error value.
200 _public_
int udev_enumerate_add_match_subsystem(struct udev_enumerate
*udev_enumerate
, const char *subsystem
) {
201 assert_return(udev_enumerate
, -EINVAL
);
206 return sd_device_enumerator_add_match_subsystem(udev_enumerate
->enumerator
, subsystem
, true);
210 * udev_enumerate_add_nomatch_subsystem:
211 * @udev_enumerate: context
212 * @subsystem: filter for a subsystem of the device to exclude from the list
214 * Match only devices not belonging to a certain kernel subsystem.
216 * Returns: 0 on success, otherwise a negative error value.
218 _public_
int udev_enumerate_add_nomatch_subsystem(struct udev_enumerate
*udev_enumerate
, const char *subsystem
) {
219 assert_return(udev_enumerate
, -EINVAL
);
224 return sd_device_enumerator_add_match_subsystem(udev_enumerate
->enumerator
, subsystem
, false);
228 * udev_enumerate_add_match_sysattr:
229 * @udev_enumerate: context
230 * @sysattr: filter for a sys attribute at the device to include in the list
231 * @value: optional value of the sys attribute
233 * Match only devices with a certain /sys device attribute.
235 * Returns: 0 on success, otherwise a negative error value.
237 _public_
int udev_enumerate_add_match_sysattr(struct udev_enumerate
*udev_enumerate
, const char *sysattr
, const char *value
) {
238 assert_return(udev_enumerate
, -EINVAL
);
243 return sd_device_enumerator_add_match_sysattr(udev_enumerate
->enumerator
, sysattr
, value
, true);
247 * udev_enumerate_add_nomatch_sysattr:
248 * @udev_enumerate: context
249 * @sysattr: filter for a sys attribute at the device to exclude from the list
250 * @value: optional value of the sys attribute
252 * Match only devices not having a certain /sys device attribute.
254 * Returns: 0 on success, otherwise a negative error value.
256 _public_
int udev_enumerate_add_nomatch_sysattr(struct udev_enumerate
*udev_enumerate
, const char *sysattr
, const char *value
) {
257 assert_return(udev_enumerate
, -EINVAL
);
262 return sd_device_enumerator_add_match_sysattr(udev_enumerate
->enumerator
, sysattr
, value
, false);
266 * udev_enumerate_add_match_property:
267 * @udev_enumerate: context
268 * @property: filter for a property of the device to include in the list
269 * @value: value of the property
271 * Match only devices with a certain property.
273 * Returns: 0 on success, otherwise a negative error value.
275 _public_
int udev_enumerate_add_match_property(struct udev_enumerate
*udev_enumerate
, const char *property
, const char *value
) {
276 assert_return(udev_enumerate
, -EINVAL
);
281 return sd_device_enumerator_add_match_property(udev_enumerate
->enumerator
, property
, value
);
285 * udev_enumerate_add_match_tag:
286 * @udev_enumerate: context
287 * @tag: filter for a tag of the device to include in the list
289 * Match only devices with a certain tag.
291 * Returns: 0 on success, otherwise a negative error value.
293 _public_
int udev_enumerate_add_match_tag(struct udev_enumerate
*udev_enumerate
, const char *tag
) {
294 assert_return(udev_enumerate
, -EINVAL
);
299 return sd_device_enumerator_add_match_tag(udev_enumerate
->enumerator
, tag
);
303 * udev_enumerate_add_match_parent:
304 * @udev_enumerate: context
305 * @parent: parent device where to start searching
307 * Return the devices on the subtree of one given device. The parent
308 * itself is included in the list.
310 * A reference for the device is held until the udev_enumerate context
313 * Returns: 0 on success, otherwise a negative error value.
315 _public_
int udev_enumerate_add_match_parent(struct udev_enumerate
*udev_enumerate
, struct udev_device
*parent
) {
316 assert_return(udev_enumerate
, -EINVAL
);
321 return sd_device_enumerator_add_match_parent(udev_enumerate
->enumerator
, parent
->device
);
325 * udev_enumerate_add_match_is_initialized:
326 * @udev_enumerate: context
328 * Match only devices which udev has set up already. This makes
329 * sure, that the device node permissions and context are properly set
330 * and that network devices are fully renamed.
332 * Usually, devices which are found in the kernel but not already
333 * handled by udev, have still pending events. Services should subscribe
334 * to monitor events and wait for these devices to become ready, instead
335 * of using uninitialized devices.
337 * For now, this will not affect devices which do not have a device node
338 * and are not network interfaces.
340 * Returns: 0 on success, otherwise a negative error value.
342 _public_
int udev_enumerate_add_match_is_initialized(struct udev_enumerate
*udev_enumerate
) {
343 assert_return(udev_enumerate
, -EINVAL
);
345 return device_enumerator_add_match_is_initialized(udev_enumerate
->enumerator
);
349 * udev_enumerate_add_match_sysname:
350 * @udev_enumerate: context
351 * @sysname: filter for the name of the device to include in the list
353 * Match only devices with a given /sys device name.
355 * Returns: 0 on success, otherwise a negative error value.
357 _public_
int udev_enumerate_add_match_sysname(struct udev_enumerate
*udev_enumerate
, const char *sysname
) {
358 assert_return(udev_enumerate
, -EINVAL
);
363 return sd_device_enumerator_add_match_sysname(udev_enumerate
->enumerator
, sysname
);
367 * udev_enumerate_add_syspath:
368 * @udev_enumerate: context
369 * @syspath: path of a device
371 * Add a device to the list of devices, to retrieve it back sorted in dependency order.
373 * Returns: 0 on success, otherwise a negative error value.
375 _public_
int udev_enumerate_add_syspath(struct udev_enumerate
*udev_enumerate
, const char *syspath
) {
376 _cleanup_(sd_device_unrefp
) sd_device
*device
= NULL
;
379 assert_return(udev_enumerate
, -EINVAL
);
384 r
= sd_device_new_from_syspath(&device
, syspath
);
388 r
= device_enumerator_add_device(udev_enumerate
->enumerator
, device
);
396 * udev_enumerate_scan_devices:
397 * @udev_enumerate: udev enumeration context
399 * Scan /sys for all devices which match the given filters. No matches
400 * will return all currently available devices.
402 * Returns: 0 on success, otherwise a negative error value.
404 _public_
int udev_enumerate_scan_devices(struct udev_enumerate
*udev_enumerate
) {
405 assert_return(udev_enumerate
, -EINVAL
);
407 return device_enumerator_scan_devices(udev_enumerate
->enumerator
);
411 * udev_enumerate_scan_subsystems:
412 * @udev_enumerate: udev enumeration context
414 * Scan /sys for all kernel subsystems, including buses, classes, drivers.
416 * Returns: 0 on success, otherwise a negative error value.
418 _public_
int udev_enumerate_scan_subsystems(struct udev_enumerate
*udev_enumerate
) {
419 assert_return(udev_enumerate
, -EINVAL
);
421 return device_enumerator_scan_subsystems(udev_enumerate
->enumerator
);