]>
git.ipfire.org Git - thirdparty/systemd.git/blob - src/libudev/libudev-device.c
d3a3c53969728dc2b519e3df2a61fbfb81095b8f
1 /* SPDX-License-Identifier: LGPL-2.1+ */
7 #include <linux/sockios.h>
14 #include <sys/ioctl.h>
15 #include <sys/socket.h>
20 #include "sd-device.h"
22 #include "alloc-util.h"
23 #include "device-private.h"
24 #include "device-util.h"
25 #include "libudev-device-internal.h"
26 #include "parse-util.h"
27 #include "time-util.h"
30 * SECTION:libudev-device
31 * @short_description: kernel sys devices
33 * Representation of kernel sys devices. Devices are uniquely identified
34 * by their syspath, every device has exactly one path in the kernel sys
35 * filesystem. Devices usually belong to a kernel subsystem, and have
36 * a unique name inside that subsystem.
40 * udev_device_get_seqnum:
41 * @udev_device: udev device
43 * This is only valid if the device was received through a monitor. Devices read from
44 * sys do not have a sequence number.
46 * Returns: the kernel event sequence number, or 0 if there is no sequence number available.
48 _public_
unsigned long long udev_device_get_seqnum(struct udev_device
*udev_device
) {
51 assert_return_errno(udev_device
, 0, EINVAL
);
53 if (device_get_seqnum(udev_device
->device
, &seqnum
) < 0)
60 * udev_device_get_devnum:
61 * @udev_device: udev device
63 * Get the device major/minor number.
65 * Returns: the dev_t number.
67 _public_ dev_t
udev_device_get_devnum(struct udev_device
*udev_device
) {
71 assert_return_errno(udev_device
, makedev(0, 0), EINVAL
);
73 r
= sd_device_get_devnum(udev_device
->device
, &devnum
);
77 return_with_errno(makedev(0, 0), r
);
83 * udev_device_get_driver:
84 * @udev_device: udev device
86 * Get the kernel driver name.
88 * Returns: the driver name string, or #NULL if there is no driver attached.
90 _public_
const char *udev_device_get_driver(struct udev_device
*udev_device
) {
94 assert_return_errno(udev_device
, NULL
, EINVAL
);
96 r
= sd_device_get_driver(udev_device
->device
, &driver
);
98 return_with_errno(NULL
, r
);
104 * udev_device_get_devtype:
105 * @udev_device: udev device
107 * Retrieve the devtype string of the udev device.
109 * Returns: the devtype name of the udev device, or #NULL if it cannot be determined
111 _public_
const char *udev_device_get_devtype(struct udev_device
*udev_device
) {
115 assert_return_errno(udev_device
, NULL
, EINVAL
);
117 r
= sd_device_get_devtype(udev_device
->device
, &devtype
);
121 return_with_errno(NULL
, r
);
127 * udev_device_get_subsystem:
128 * @udev_device: udev device
130 * Retrieve the subsystem string of the udev device. The string does not
133 * Returns: the subsystem name of the udev device, or #NULL if it cannot be determined
135 _public_
const char *udev_device_get_subsystem(struct udev_device
*udev_device
) {
136 const char *subsystem
;
139 assert_return_errno(udev_device
, NULL
, EINVAL
);
141 r
= sd_device_get_subsystem(udev_device
->device
, &subsystem
);
143 return_with_errno(NULL
, r
);
149 * udev_device_get_property_value:
150 * @udev_device: udev device
151 * @key: property name
153 * Get the value of a given property.
155 * Returns: the property string, or #NULL if there is no such property.
157 _public_
const char *udev_device_get_property_value(struct udev_device
*udev_device
, const char *key
) {
161 assert_return_errno(udev_device
&& key
, NULL
, EINVAL
);
163 r
= sd_device_get_property_value(udev_device
->device
, key
, &value
);
165 return_with_errno(NULL
, r
);
170 struct udev_device
*udev_device_new(struct udev
*udev
, sd_device
*device
) {
171 _cleanup_(udev_list_freep
) struct udev_list
*properties
= NULL
, *tags
= NULL
, *sysattrs
= NULL
, *devlinks
= NULL
;
172 struct udev_device
*udev_device
;
176 properties
= udev_list_new(true);
178 return_with_errno(NULL
, ENOMEM
);
179 tags
= udev_list_new(true);
181 return_with_errno(NULL
, ENOMEM
);
182 sysattrs
= udev_list_new(true);
184 return_with_errno(NULL
, ENOMEM
);
185 devlinks
= udev_list_new(true);
187 return_with_errno(NULL
, ENOMEM
);
189 udev_device
= new(struct udev_device
, 1);
191 return_with_errno(NULL
, ENOMEM
);
193 *udev_device
= (struct udev_device
) {
196 .device
= sd_device_ref(device
),
197 .properties
= TAKE_PTR(properties
),
198 .tags
= TAKE_PTR(tags
),
199 .sysattrs
= TAKE_PTR(sysattrs
),
200 .devlinks
= TAKE_PTR(devlinks
),
207 * udev_device_new_from_syspath:
208 * @udev: udev library context
209 * @syspath: sys device path including sys directory
211 * Create new udev device, and fill in information from the sys
212 * device and the udev database entry. The syspath is the absolute
213 * path to the device, including the sys mount point.
215 * The initial refcount is 1, and needs to be decremented to
216 * release the resources of the udev device.
218 * Returns: a new udev device, or #NULL, if it does not exist
220 _public_
struct udev_device
*udev_device_new_from_syspath(struct udev
*udev
, const char *syspath
) {
221 _cleanup_(sd_device_unrefp
) sd_device
*device
= NULL
;
224 r
= sd_device_new_from_syspath(&device
, syspath
);
226 return_with_errno(NULL
, r
);
228 return udev_device_new(udev
, device
);
232 * udev_device_new_from_devnum:
233 * @udev: udev library context
234 * @type: char or block device
235 * @devnum: device major/minor number
237 * Create new udev device, and fill in information from the sys
238 * device and the udev database entry. The device is looked-up
239 * by its major/minor number and type. Character and block device
240 * numbers are not unique across the two types.
242 * The initial refcount is 1, and needs to be decremented to
243 * release the resources of the udev device.
245 * Returns: a new udev device, or #NULL, if it does not exist
247 _public_
struct udev_device
*udev_device_new_from_devnum(struct udev
*udev
, char type
, dev_t devnum
) {
248 _cleanup_(sd_device_unrefp
) sd_device
*device
= NULL
;
251 r
= sd_device_new_from_devnum(&device
, type
, devnum
);
253 return_with_errno(NULL
, r
);
255 return udev_device_new(udev
, device
);
259 * udev_device_new_from_device_id:
260 * @udev: udev library context
261 * @id: text string identifying a kernel device
263 * Create new udev device, and fill in information from the sys
264 * device and the udev database entry. The device is looked-up
265 * by a special string:
266 * b8:2 - block device major:minor
267 * c128:1 - char device major:minor
268 * n3 - network device ifindex
269 * +sound:card29 - kernel driver core subsystem:device name
271 * The initial refcount is 1, and needs to be decremented to
272 * release the resources of the udev device.
274 * Returns: a new udev device, or #NULL, if it does not exist
276 _public_
struct udev_device
*udev_device_new_from_device_id(struct udev
*udev
, const char *id
) {
277 _cleanup_(sd_device_unrefp
) sd_device
*device
= NULL
;
280 r
= sd_device_new_from_device_id(&device
, id
);
282 return_with_errno(NULL
, r
);
284 return udev_device_new(udev
, device
);
288 * udev_device_new_from_subsystem_sysname:
289 * @udev: udev library context
290 * @subsystem: the subsystem of the device
291 * @sysname: the name of the device
293 * Create new udev device, and fill in information from the sys device
294 * and the udev database entry. The device is looked up by the subsystem
295 * and name string of the device, like "mem" / "zero", or "block" / "sda".
297 * The initial refcount is 1, and needs to be decremented to
298 * release the resources of the udev device.
300 * Returns: a new udev device, or #NULL, if it does not exist
302 _public_
struct udev_device
*udev_device_new_from_subsystem_sysname(struct udev
*udev
, const char *subsystem
, const char *sysname
) {
303 _cleanup_(sd_device_unrefp
) sd_device
*device
= NULL
;
306 r
= sd_device_new_from_subsystem_sysname(&device
, subsystem
, sysname
);
308 return_with_errno(NULL
, r
);
310 return udev_device_new(udev
, device
);
314 * udev_device_new_from_environment
315 * @udev: udev library context
317 * Create new udev device, and fill in information from the
318 * current process environment. This only works reliable if
319 * the process is called from a udev rule. It is usually used
320 * for tools executed from IMPORT= rules.
322 * The initial refcount is 1, and needs to be decremented to
323 * release the resources of the udev device.
325 * Returns: a new udev device, or #NULL, if it does not exist
327 _public_
struct udev_device
*udev_device_new_from_environment(struct udev
*udev
) {
328 _cleanup_(sd_device_unrefp
) sd_device
*device
= NULL
;
331 r
= device_new_from_strv(&device
, environ
);
333 return_with_errno(NULL
, r
);
335 return udev_device_new(udev
, device
);
338 static struct udev_device
*device_new_from_parent(struct udev_device
*child
) {
342 assert_return_errno(child
, NULL
, EINVAL
);
344 r
= sd_device_get_parent(child
->device
, &parent
);
346 return_with_errno(NULL
, r
);
348 return udev_device_new(child
->udev
, parent
);
352 * udev_device_get_parent:
353 * @udev_device: the device to start searching from
355 * Find the next parent device, and fill in information from the sys
356 * device and the udev database entry.
358 * Returned device is not referenced. It is attached to the child
359 * device, and will be cleaned up when the child device is cleaned up.
361 * It is not necessarily just the upper level directory, empty or not
362 * recognized sys directories are ignored.
364 * It can be called as many times as needed, without caring about
367 * Returns: a new udev device, or #NULL, if it no parent exist.
369 _public_
struct udev_device
*udev_device_get_parent(struct udev_device
*udev_device
) {
370 assert_return_errno(udev_device
, NULL
, EINVAL
);
372 if (!udev_device
->parent_set
) {
373 udev_device
->parent_set
= true;
374 udev_device
->parent
= device_new_from_parent(udev_device
);
377 /* TODO: errno will differ here in case parent == NULL */
378 return udev_device
->parent
;
382 * udev_device_get_parent_with_subsystem_devtype:
383 * @udev_device: udev device to start searching from
384 * @subsystem: the subsystem of the device
385 * @devtype: the type (DEVTYPE) of the device
387 * Find the next parent device, with a matching subsystem and devtype
388 * value, and fill in information from the sys device and the udev
391 * If devtype is #NULL, only subsystem is checked, and any devtype will
394 * Returned device is not referenced. It is attached to the child
395 * device, and will be cleaned up when the child device is cleaned up.
397 * It can be called as many times as needed, without caring about
400 * Returns: a new udev device, or #NULL if no matching parent exists.
402 _public_
struct udev_device
*udev_device_get_parent_with_subsystem_devtype(struct udev_device
*udev_device
, const char *subsystem
, const char *devtype
) {
406 assert_return_errno(udev_device
, NULL
, EINVAL
);
408 /* this relies on the fact that finding the subdevice of a parent or the
409 parent of a subdevice commute */
411 /* first find the correct sd_device */
412 r
= sd_device_get_parent_with_subsystem_devtype(udev_device
->device
, subsystem
, devtype
, &parent
);
414 return_with_errno(NULL
, r
);
416 /* then walk the chain of udev_device parents until the corresponding
418 while ((udev_device
= udev_device_get_parent(udev_device
)))
419 if (udev_device
->device
== parent
)
422 return_with_errno(NULL
, ENOENT
);
426 * udev_device_get_udev:
427 * @udev_device: udev device
429 * Retrieve the udev library context the device was created with.
431 * Returns: the udev library context
433 _public_
struct udev
*udev_device_get_udev(struct udev_device
*udev_device
) {
434 assert_return_errno(udev_device
, NULL
, EINVAL
);
436 return udev_device
->udev
;
439 static struct udev_device
*udev_device_free(struct udev_device
*udev_device
) {
442 sd_device_unref(udev_device
->device
);
443 udev_device_unref(udev_device
->parent
);
445 udev_list_free(udev_device
->properties
);
446 udev_list_free(udev_device
->sysattrs
);
447 udev_list_free(udev_device
->tags
);
448 udev_list_free(udev_device
->devlinks
);
450 return mfree(udev_device
);
455 * @udev_device: udev device
457 * Take a reference of a udev device.
459 * Returns: the passed udev device
464 * @udev_device: udev device
466 * Drop a reference of a udev device. If the refcount reaches zero,
467 * the resources of the device will be released.
471 DEFINE_PUBLIC_TRIVIAL_REF_UNREF_FUNC(struct udev_device
, udev_device
, udev_device_free
);
474 * udev_device_get_devpath:
475 * @udev_device: udev device
477 * Retrieve the kernel devpath value of the udev device. The path
478 * does not contain the sys mount point, and starts with a '/'.
480 * Returns: the devpath of the udev device
482 _public_
const char *udev_device_get_devpath(struct udev_device
*udev_device
) {
486 assert_return_errno(udev_device
, NULL
, EINVAL
);
488 r
= sd_device_get_devpath(udev_device
->device
, &devpath
);
490 return_with_errno(NULL
, r
);
496 * udev_device_get_syspath:
497 * @udev_device: udev device
499 * Retrieve the sys path of the udev device. The path is an
500 * absolute path and starts with the sys mount point.
502 * Returns: the sys path of the udev device
504 _public_
const char *udev_device_get_syspath(struct udev_device
*udev_device
) {
508 assert_return_errno(udev_device
, NULL
, EINVAL
);
510 r
= sd_device_get_syspath(udev_device
->device
, &syspath
);
512 return_with_errno(NULL
, r
);
518 * udev_device_get_sysname:
519 * @udev_device: udev device
521 * Get the kernel device name in /sys.
523 * Returns: the name string of the device
525 _public_
const char *udev_device_get_sysname(struct udev_device
*udev_device
) {
529 assert_return_errno(udev_device
, NULL
, EINVAL
);
531 r
= sd_device_get_sysname(udev_device
->device
, &sysname
);
533 return_with_errno(NULL
, r
);
539 * udev_device_get_sysnum:
540 * @udev_device: udev device
542 * Get the instance number of the device.
544 * Returns: the trailing number string of the device name
546 _public_
const char *udev_device_get_sysnum(struct udev_device
*udev_device
) {
550 assert_return_errno(udev_device
, NULL
, EINVAL
);
552 r
= sd_device_get_sysnum(udev_device
->device
, &sysnum
);
556 return_with_errno(NULL
, r
);
562 * udev_device_get_devnode:
563 * @udev_device: udev device
565 * Retrieve the device node file name belonging to the udev device.
566 * The path is an absolute path, and starts with the device directory.
568 * Returns: the device node file name of the udev device, or #NULL if no device node exists
570 _public_
const char *udev_device_get_devnode(struct udev_device
*udev_device
) {
574 assert_return_errno(udev_device
, NULL
, EINVAL
);
576 r
= sd_device_get_devname(udev_device
->device
, &devnode
);
578 return_with_errno(NULL
, r
);
584 * udev_device_get_devlinks_list_entry:
585 * @udev_device: udev device
587 * Retrieve the list of device links pointing to the device file of
588 * the udev device. The next list entry can be retrieved with
589 * udev_list_entry_get_next(), which returns #NULL if no more entries exist.
590 * The devlink path can be retrieved from the list entry by
591 * udev_list_entry_get_name(). The path is an absolute path, and starts with
592 * the device directory.
594 * Returns: the first entry of the device node link list
596 _public_
struct udev_list_entry
*udev_device_get_devlinks_list_entry(struct udev_device
*udev_device
) {
597 assert_return_errno(udev_device
, NULL
, EINVAL
);
599 if (device_get_devlinks_generation(udev_device
->device
) != udev_device
->devlinks_generation
||
600 !udev_device
->devlinks_read
) {
603 udev_list_cleanup(udev_device
->devlinks
);
605 FOREACH_DEVICE_DEVLINK(udev_device
->device
, devlink
)
606 if (!udev_list_entry_add(udev_device
->devlinks
, devlink
, NULL
))
607 return_with_errno(NULL
, ENOMEM
);
609 udev_device
->devlinks_read
= true;
610 udev_device
->devlinks_generation
= device_get_devlinks_generation(udev_device
->device
);
613 return udev_list_get_entry(udev_device
->devlinks
);
617 * udev_device_get_event_properties_entry:
618 * @udev_device: udev device
620 * Retrieve the list of key/value device properties of the udev
621 * device. The next list entry can be retrieved with udev_list_entry_get_next(),
622 * which returns #NULL if no more entries exist. The property name
623 * can be retrieved from the list entry by udev_list_entry_get_name(),
624 * the property value by udev_list_entry_get_value().
626 * Returns: the first entry of the property list
628 _public_
struct udev_list_entry
*udev_device_get_properties_list_entry(struct udev_device
*udev_device
) {
629 assert_return_errno(udev_device
, NULL
, EINVAL
);
631 if (device_get_properties_generation(udev_device
->device
) != udev_device
->properties_generation
||
632 !udev_device
->properties_read
) {
633 const char *key
, *value
;
635 udev_list_cleanup(udev_device
->properties
);
637 FOREACH_DEVICE_PROPERTY(udev_device
->device
, key
, value
)
638 if (!udev_list_entry_add(udev_device
->properties
, key
, value
))
639 return_with_errno(NULL
, ENOMEM
);
641 udev_device
->properties_read
= true;
642 udev_device
->properties_generation
= device_get_properties_generation(udev_device
->device
);
645 return udev_list_get_entry(udev_device
->properties
);
649 * udev_device_get_action:
650 * @udev_device: udev device
652 * This is only valid if the device was received through a monitor. Devices read from
653 * sys do not have an action string. Usual actions are: add, remove, change, online,
656 * Returns: the kernel action value, or #NULL if there is no action value available.
658 _public_
const char *udev_device_get_action(struct udev_device
*udev_device
) {
661 assert_return_errno(udev_device
, NULL
, EINVAL
);
663 if (device_get_action(udev_device
->device
, &action
) < 0)
666 return device_action_to_string(action
);
670 * udev_device_get_usec_since_initialized:
671 * @udev_device: udev device
673 * Return the number of microseconds passed since udev set up the
674 * device for the first time.
676 * This is only implemented for devices with need to store properties
677 * in the udev database. All other devices return 0 here.
679 * Returns: the number of microseconds since the device was first seen.
681 _public_
unsigned long long int udev_device_get_usec_since_initialized(struct udev_device
*udev_device
) {
685 assert_return(udev_device
, -EINVAL
);
687 r
= sd_device_get_usec_since_initialized(udev_device
->device
, &ts
);
689 return_with_errno(0, r
);
695 * udev_device_get_sysattr_value:
696 * @udev_device: udev device
697 * @sysattr: attribute name
699 * The retrieved value is cached in the device. Repeated calls will return the same
700 * value and not open the attribute again.
702 * Returns: the content of a sys attribute file, or #NULL if there is no sys attribute value.
704 _public_
const char *udev_device_get_sysattr_value(struct udev_device
*udev_device
, const char *sysattr
) {
708 assert_return_errno(udev_device
, NULL
, EINVAL
);
710 r
= sd_device_get_sysattr_value(udev_device
->device
, sysattr
, &value
);
712 return_with_errno(NULL
, r
);
718 * udev_device_set_sysattr_value:
719 * @udev_device: udev device
720 * @sysattr: attribute name
721 * @value: new value to be set
723 * Update the contents of the sys attribute and the cached value of the device.
725 * Returns: Negative error code on failure or 0 on success.
727 _public_
int udev_device_set_sysattr_value(struct udev_device
*udev_device
, const char *sysattr
, const char *value
) {
730 assert_return(udev_device
, -EINVAL
);
732 r
= sd_device_set_sysattr_value(udev_device
->device
, sysattr
, value
);
740 * udev_device_get_sysattr_list_entry:
741 * @udev_device: udev device
743 * Retrieve the list of available sysattrs, with value being empty;
744 * This just return all available sysfs attributes for a particular
745 * device without reading their values.
747 * Returns: the first entry of the property list
749 _public_
struct udev_list_entry
*udev_device_get_sysattr_list_entry(struct udev_device
*udev_device
) {
750 assert_return_errno(udev_device
, NULL
, EINVAL
);
752 if (!udev_device
->sysattrs_read
) {
755 udev_list_cleanup(udev_device
->sysattrs
);
757 FOREACH_DEVICE_SYSATTR(udev_device
->device
, sysattr
)
758 if (!udev_list_entry_add(udev_device
->sysattrs
, sysattr
, NULL
))
759 return_with_errno(NULL
, ENOMEM
);
761 udev_device
->sysattrs_read
= true;
764 return udev_list_get_entry(udev_device
->sysattrs
);
768 * udev_device_get_is_initialized:
769 * @udev_device: udev device
771 * Check if udev has already handled the device and has set up
772 * device node permissions and context, or has renamed a network
775 * This is only implemented for devices with a device node
776 * or network interfaces. All other devices return 1 here.
778 * Returns: 1 if the device is set up. 0 otherwise.
780 _public_
int udev_device_get_is_initialized(struct udev_device
*udev_device
) {
783 assert_return(udev_device
, -EINVAL
);
785 r
= sd_device_get_is_initialized(udev_device
->device
);
787 return_with_errno(0, r
);
793 * udev_device_get_tags_list_entry:
794 * @udev_device: udev device
796 * Retrieve the list of tags attached to the udev device. The next
797 * list entry can be retrieved with udev_list_entry_get_next(),
798 * which returns #NULL if no more entries exist. The tag string
799 * can be retrieved from the list entry by udev_list_entry_get_name().
801 * Returns: the first entry of the tag list
803 _public_
struct udev_list_entry
*udev_device_get_tags_list_entry(struct udev_device
*udev_device
) {
804 assert_return_errno(udev_device
, NULL
, EINVAL
);
806 if (device_get_tags_generation(udev_device
->device
) != udev_device
->tags_generation
||
807 !udev_device
->tags_read
) {
810 udev_list_cleanup(udev_device
->tags
);
812 FOREACH_DEVICE_TAG(udev_device
->device
, tag
)
813 if (!udev_list_entry_add(udev_device
->tags
, tag
, NULL
))
814 return_with_errno(NULL
, ENOMEM
);
816 udev_device
->tags_read
= true;
817 udev_device
->tags_generation
= device_get_tags_generation(udev_device
->device
);
820 return udev_list_get_entry(udev_device
->tags
);
824 * udev_device_has_tag:
825 * @udev_device: udev device
828 * Check if a given device has a certain tag associated.
830 * Returns: 1 if the tag is found. 0 otherwise.
832 _public_
int udev_device_has_tag(struct udev_device
*udev_device
, const char *tag
) {
833 assert_return(udev_device
, 0);
835 return sd_device_has_tag(udev_device
->device
, tag
) > 0;