src/libudev/libudev-device.c

   1 /* SPDX-License-Identifier: LGPL-2.1+ */
   2
   3 #include <ctype.h>
   4 #include <dirent.h>
   5 #include <errno.h>
   6 #include <fcntl.h>
   7 #include <linux/sockios.h>
   8 #include <net/if.h>
   9 #include <stdbool.h>
  10 #include <stddef.h>
  11 #include <stdio.h>
  12 #include <stdlib.h>
  13 #include <string.h>
  14 #include <sys/ioctl.h>
  15 #include <sys/socket.h>
  16 #include <sys/stat.h>
  17 #include <unistd.h>
  18
  19 #include "libudev.h"
  20 #include "sd-device.h"
  21
  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"
  28
  29 /**
  30  * SECTION:libudev-device
  31  * @short_description: kernel sys devices
  32  *
  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.
  37  */
  38
  39 /**
  40  * udev_device_get_seqnum:
  41  * @udev_device: udev device
  42  *
  43  * This is only valid if the device was received through a monitor. Devices read from
  44  * sys do not have a sequence number.
  45  *
  46  * Returns: the kernel event sequence number, or 0 if there is no sequence number available.
  47  **/
  48 _public_ unsigned long long udev_device_get_seqnum(struct udev_device *udev_device) {
  49         uint64_t seqnum;
  50
  51         assert_return_errno(udev_device, 0, EINVAL);
  52
  53         if (device_get_seqnum(udev_device->device, &seqnum) < 0)
  54                 return 0;
  55
  56         return seqnum;
  57 }
  58
  59 /**
  60  * udev_device_get_devnum:
  61  * @udev_device: udev device
  62  *
  63  * Get the device major/minor number.
  64  *
  65  * Returns: the dev_t number.
  66  **/
  67 _public_ dev_t udev_device_get_devnum(struct udev_device *udev_device) {
  68         dev_t devnum;
  69         int r;
  70
  71         assert_return_errno(udev_device, makedev(0, 0), EINVAL);
  72
  73         r = sd_device_get_devnum(udev_device->device, &devnum);
  74         if (r == -ENOENT)
  75                 return makedev(0, 0);
  76         if (r < 0)
  77                 return_with_errno(makedev(0, 0), r);
  78
  79         return devnum;
  80 }
  81
  82 /**
  83  * udev_device_get_driver:
  84  * @udev_device: udev device
  85  *
  86  * Get the kernel driver name.
  87  *
  88  * Returns: the driver name string, or #NULL if there is no driver attached.
  89  **/
  90 _public_ const char *udev_device_get_driver(struct udev_device *udev_device) {
  91         const char *driver;
  92         int r;
  93
  94         assert_return_errno(udev_device, NULL, EINVAL);
  95
  96         r = sd_device_get_driver(udev_device->device, &driver);
  97         if (r < 0)
  98                 return_with_errno(NULL, r);
  99
 100         return driver;
 101 }
 102
 103 /**
 104  * udev_device_get_devtype:
 105  * @udev_device: udev device
 106  *
 107  * Retrieve the devtype string of the udev device.
 108  *
 109  * Returns: the devtype name of the udev device, or #NULL if it cannot be determined
 110  **/
 111 _public_ const char *udev_device_get_devtype(struct udev_device *udev_device) {
 112         const char *devtype;
 113         int r;
 114
 115         assert_return_errno(udev_device, NULL, EINVAL);
 116
 117         r = sd_device_get_devtype(udev_device->device, &devtype);
 118         if (r == -ENOENT)
 119                 return NULL;
 120         if (r < 0)
 121                 return_with_errno(NULL, r);
 122
 123         return devtype;
 124 }
 125
 126 /**
 127  * udev_device_get_subsystem:
 128  * @udev_device: udev device
 129  *
 130  * Retrieve the subsystem string of the udev device. The string does not
 131  * contain any "/".
 132  *
 133  * Returns: the subsystem name of the udev device, or #NULL if it cannot be determined
 134  **/
 135 _public_ const char *udev_device_get_subsystem(struct udev_device *udev_device) {
 136         const char *subsystem;
 137         int r;
 138
 139         assert_return_errno(udev_device, NULL, EINVAL);
 140
 141         r = sd_device_get_subsystem(udev_device->device, &subsystem);
 142         if (r < 0)
 143                 return_with_errno(NULL, r);
 144
 145         return subsystem;
 146 }
 147
 148 /**
 149  * udev_device_get_property_value:
 150  * @udev_device: udev device
 151  * @key: property name
 152  *
 153  * Get the value of a given property.
 154  *
 155  * Returns: the property string, or #NULL if there is no such property.
 156  **/
 157 _public_ const char *udev_device_get_property_value(struct udev_device *udev_device, const char *key) {
 158         const char *value;
 159         int r;
 160
 161         assert_return_errno(udev_device && key, NULL, EINVAL);
 162
 163         r = sd_device_get_property_value(udev_device->device, key, &value);
 164         if (r < 0)
 165                 return_with_errno(NULL, r);
 166
 167         return value;
 168 }
 169
 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;
 173
 174         assert(device);
 175
 176         properties = udev_list_new(true);
 177         if (!properties)
 178                 return_with_errno(NULL, ENOMEM);
 179         tags = udev_list_new(true);
 180         if (!tags)
 181                 return_with_errno(NULL, ENOMEM);
 182         sysattrs = udev_list_new(true);
 183         if (!sysattrs)
 184                 return_with_errno(NULL, ENOMEM);
 185         devlinks = udev_list_new(true);
 186         if (!devlinks)
 187                 return_with_errno(NULL, ENOMEM);
 188
 189         udev_device = new(struct udev_device, 1);
 190         if (!udev_device)
 191                 return_with_errno(NULL, ENOMEM);
 192
 193         *udev_device = (struct udev_device) {
 194                 .n_ref = 1,
 195                 .udev = udev,
 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),
 201         };
 202
 203         return udev_device;
 204 }
 205
 206 /**
 207  * udev_device_new_from_syspath:
 208  * @udev: udev library context
 209  * @syspath: sys device path including sys directory
 210  *
 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.
 214  *
 215  * The initial refcount is 1, and needs to be decremented to
 216  * release the resources of the udev device.
 217  *
 218  * Returns: a new udev device, or #NULL, if it does not exist
 219  **/
 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;
 222         int r;
 223
 224         r = sd_device_new_from_syspath(&device, syspath);
 225         if (r < 0)
 226                 return_with_errno(NULL, r);
 227
 228         return udev_device_new(udev, device);
 229 }
 230
 231 /**
 232  * udev_device_new_from_devnum:
 233  * @udev: udev library context
 234  * @type: char or block device
 235  * @devnum: device major/minor number
 236  *
 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.
 241  *
 242  * The initial refcount is 1, and needs to be decremented to
 243  * release the resources of the udev device.
 244  *
 245  * Returns: a new udev device, or #NULL, if it does not exist
 246  **/
 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;
 249         int r;
 250
 251         r = sd_device_new_from_devnum(&device, type, devnum);
 252         if (r < 0)
 253                 return_with_errno(NULL, r);
 254
 255         return udev_device_new(udev, device);
 256 }
 257
 258 /**
 259  * udev_device_new_from_device_id:
 260  * @udev: udev library context
 261  * @id: text string identifying a kernel device
 262  *
 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
 270  *
 271  * The initial refcount is 1, and needs to be decremented to
 272  * release the resources of the udev device.
 273  *
 274  * Returns: a new udev device, or #NULL, if it does not exist
 275  **/
 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;
 278         int r;
 279
 280         r = sd_device_new_from_device_id(&device, id);
 281         if (r < 0)
 282                 return_with_errno(NULL, r);
 283
 284         return udev_device_new(udev, device);
 285 }
 286
 287 /**
 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
 292  *
 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".
 296  *
 297  * The initial refcount is 1, and needs to be decremented to
 298  * release the resources of the udev device.
 299  *
 300  * Returns: a new udev device, or #NULL, if it does not exist
 301  **/
 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;
 304         int r;
 305
 306         r = sd_device_new_from_subsystem_sysname(&device, subsystem, sysname);
 307         if (r < 0)
 308                 return_with_errno(NULL, r);
 309
 310         return udev_device_new(udev, device);
 311 }
 312
 313 /**
 314  * udev_device_new_from_environment
 315  * @udev: udev library context
 316  *
 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.
 321  *
 322  * The initial refcount is 1, and needs to be decremented to
 323  * release the resources of the udev device.
 324  *
 325  * Returns: a new udev device, or #NULL, if it does not exist
 326  **/
 327 _public_ struct udev_device *udev_device_new_from_environment(struct udev *udev) {
 328         _cleanup_(sd_device_unrefp) sd_device *device = NULL;
 329         int r;
 330
 331         r = device_new_from_strv(&device, environ);
 332         if (r < 0)
 333                 return_with_errno(NULL, r);
 334
 335         return udev_device_new(udev, device);
 336 }
 337
 338 static struct udev_device *device_new_from_parent(struct udev_device *child) {
 339         sd_device *parent;
 340         int r;
 341
 342         assert_return_errno(child, NULL, EINVAL);
 343
 344         r = sd_device_get_parent(child->device, &parent);
 345         if (r < 0)
 346                 return_with_errno(NULL, r);
 347
 348         return udev_device_new(child->udev, parent);
 349 }
 350
 351 /**
 352  * udev_device_get_parent:
 353  * @udev_device: the device to start searching from
 354  *
 355  * Find the next parent device, and fill in information from the sys
 356  * device and the udev database entry.
 357  *
 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.
 360  *
 361  * It is not necessarily just the upper level directory, empty or not
 362  * recognized sys directories are ignored.
 363  *
 364  * It can be called as many times as needed, without caring about
 365  * references.
 366  *
 367  * Returns: a new udev device, or #NULL, if it no parent exist.
 368  **/
 369 _public_ struct udev_device *udev_device_get_parent(struct udev_device *udev_device) {
 370         assert_return_errno(udev_device, NULL, EINVAL);
 371
 372         if (!udev_device->parent_set) {
 373                 udev_device->parent_set = true;
 374                 udev_device->parent = device_new_from_parent(udev_device);
 375         }
 376
 377         /* TODO: errno will differ here in case parent == NULL */
 378         return udev_device->parent;
 379 }
 380
 381 /**
 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
 386  *
 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
 389  * database entry.
 390  *
 391  * If devtype is #NULL, only subsystem is checked, and any devtype will
 392  * match.
 393  *
 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.
 396  *
 397  * It can be called as many times as needed, without caring about
 398  * references.
 399  *
 400  * Returns: a new udev device, or #NULL if no matching parent exists.
 401  **/
 402 _public_ struct udev_device *udev_device_get_parent_with_subsystem_devtype(struct udev_device *udev_device, const char *subsystem, const char *devtype) {
 403         sd_device *parent;
 404         int r;
 405
 406         assert_return_errno(udev_device, NULL, EINVAL);
 407
 408         /* this relies on the fact that finding the subdevice of a parent or the
 409            parent of a subdevice commute */
 410
 411         /* first find the correct sd_device */
 412         r = sd_device_get_parent_with_subsystem_devtype(udev_device->device, subsystem, devtype, &parent);
 413         if (r < 0)
 414                 return_with_errno(NULL, r);
 415
 416         /* then walk the chain of udev_device parents until the corresponding
 417            one is found */
 418         while ((udev_device = udev_device_get_parent(udev_device)))
 419                 if (udev_device->device == parent)
 420                         return udev_device;
 421
 422         return_with_errno(NULL, ENOENT);
 423 }
 424
 425 /**
 426  * udev_device_get_udev:
 427  * @udev_device: udev device
 428  *
 429  * Retrieve the udev library context the device was created with.
 430  *
 431  * Returns: the udev library context
 432  **/
 433 _public_ struct udev *udev_device_get_udev(struct udev_device *udev_device) {
 434         assert_return_errno(udev_device, NULL, EINVAL);
 435
 436         return udev_device->udev;
 437 }
 438
 439 static struct udev_device *udev_device_free(struct udev_device *udev_device) {
 440         assert(udev_device);
 441
 442         sd_device_unref(udev_device->device);
 443         udev_device_unref(udev_device->parent);
 444
 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);
 449
 450         return mfree(udev_device);
 451 }
 452
 453 /**
 454  * udev_device_ref:
 455  * @udev_device: udev device
 456  *
 457  * Take a reference of a udev device.
 458  *
 459  * Returns: the passed udev device
 460  **/
 461
 462 /**
 463  * udev_device_unref:
 464  * @udev_device: udev device
 465  *
 466  * Drop a reference of a udev device. If the refcount reaches zero,
 467  * the resources of the device will be released.
 468  *
 469  * Returns: #NULL
 470  **/
 471 DEFINE_PUBLIC_TRIVIAL_REF_UNREF_FUNC(struct udev_device, udev_device, udev_device_free);
 472
 473 /**
 474  * udev_device_get_devpath:
 475  * @udev_device: udev device
 476  *
 477  * Retrieve the kernel devpath value of the udev device. The path
 478  * does not contain the sys mount point, and starts with a '/'.
 479  *
 480  * Returns: the devpath of the udev device
 481  **/
 482 _public_ const char *udev_device_get_devpath(struct udev_device *udev_device) {
 483         const char *devpath;
 484         int r;
 485
 486         assert_return_errno(udev_device, NULL, EINVAL);
 487
 488         r = sd_device_get_devpath(udev_device->device, &devpath);
 489         if (r < 0)
 490                 return_with_errno(NULL, r);
 491
 492         return devpath;
 493 }
 494
 495 /**
 496  * udev_device_get_syspath:
 497  * @udev_device: udev device
 498  *
 499  * Retrieve the sys path of the udev device. The path is an
 500  * absolute path and starts with the sys mount point.
 501  *
 502  * Returns: the sys path of the udev device
 503  **/
 504 _public_ const char *udev_device_get_syspath(struct udev_device *udev_device) {
 505         const char *syspath;
 506         int r;
 507
 508         assert_return_errno(udev_device, NULL, EINVAL);
 509
 510         r = sd_device_get_syspath(udev_device->device, &syspath);
 511         if (r < 0)
 512                 return_with_errno(NULL, r);
 513
 514         return syspath;
 515 }
 516
 517 /**
 518  * udev_device_get_sysname:
 519  * @udev_device: udev device
 520  *
 521  * Get the kernel device name in /sys.
 522  *
 523  * Returns: the name string of the device
 524  **/
 525 _public_ const char *udev_device_get_sysname(struct udev_device *udev_device) {
 526         const char *sysname;
 527         int r;
 528
 529         assert_return_errno(udev_device, NULL, EINVAL);
 530
 531         r = sd_device_get_sysname(udev_device->device, &sysname);
 532         if (r < 0)
 533                 return_with_errno(NULL, r);
 534
 535         return sysname;
 536 }
 537
 538 /**
 539  * udev_device_get_sysnum:
 540  * @udev_device: udev device
 541  *
 542  * Get the instance number of the device.
 543  *
 544  * Returns: the trailing number string of the device name
 545  **/
 546 _public_ const char *udev_device_get_sysnum(struct udev_device *udev_device) {
 547         const char *sysnum;
 548         int r;
 549
 550         assert_return_errno(udev_device, NULL, EINVAL);
 551
 552         r = sd_device_get_sysnum(udev_device->device, &sysnum);
 553         if (r == -ENOENT)
 554                 return NULL;
 555         if (r < 0)
 556                 return_with_errno(NULL, r);
 557
 558         return sysnum;
 559 }
 560
 561 /**
 562  * udev_device_get_devnode:
 563  * @udev_device: udev device
 564  *
 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.
 567  *
 568  * Returns: the device node file name of the udev device, or #NULL if no device node exists
 569  **/
 570 _public_ const char *udev_device_get_devnode(struct udev_device *udev_device) {
 571         const char *devnode;
 572         int r;
 573
 574         assert_return_errno(udev_device, NULL, EINVAL);
 575
 576         r = sd_device_get_devname(udev_device->device, &devnode);
 577         if (r < 0)
 578                 return_with_errno(NULL, r);
 579
 580         return devnode;
 581 }
 582
 583 /**
 584  * udev_device_get_devlinks_list_entry:
 585  * @udev_device: udev device
 586  *
 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.
 593  *
 594  * Returns: the first entry of the device node link list
 595  **/
 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);
 598
 599         if (device_get_devlinks_generation(udev_device->device) != udev_device->devlinks_generation ||
 600             !udev_device->devlinks_read) {
 601                 const char *devlink;
 602
 603                 udev_list_cleanup(udev_device->devlinks);
 604
 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);
 608
 609                 udev_device->devlinks_read = true;
 610                 udev_device->devlinks_generation = device_get_devlinks_generation(udev_device->device);
 611         }
 612
 613         return udev_list_get_entry(udev_device->devlinks);
 614 }
 615
 616 /**
 617  * udev_device_get_event_properties_entry:
 618  * @udev_device: udev device
 619  *
 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().
 625  *
 626  * Returns: the first entry of the property list
 627  **/
 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);
 630
 631         if (device_get_properties_generation(udev_device->device) != udev_device->properties_generation ||
 632             !udev_device->properties_read) {
 633                 const char *key, *value;
 634
 635                 udev_list_cleanup(udev_device->properties);
 636
 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);
 640
 641                 udev_device->properties_read = true;
 642                 udev_device->properties_generation = device_get_properties_generation(udev_device->device);
 643         }
 644
 645         return udev_list_get_entry(udev_device->properties);
 646 }
 647
 648 /**
 649  * udev_device_get_action:
 650  * @udev_device: udev device
 651  *
 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,
 654  * offline.
 655  *
 656  * Returns: the kernel action value, or #NULL if there is no action value available.
 657  **/
 658 _public_ const char *udev_device_get_action(struct udev_device *udev_device) {
 659         DeviceAction action;
 660
 661         assert_return_errno(udev_device, NULL, EINVAL);
 662
 663         if (device_get_action(udev_device->device, &action) < 0)
 664                 return NULL;
 665
 666         return device_action_to_string(action);
 667 }
 668
 669 /**
 670  * udev_device_get_usec_since_initialized:
 671  * @udev_device: udev device
 672  *
 673  * Return the number of microseconds passed since udev set up the
 674  * device for the first time.
 675  *
 676  * This is only implemented for devices with need to store properties
 677  * in the udev database. All other devices return 0 here.
 678  *
 679  * Returns: the number of microseconds since the device was first seen.
 680  **/
 681 _public_ unsigned long long int udev_device_get_usec_since_initialized(struct udev_device *udev_device) {
 682         usec_t ts;
 683         int r;
 684
 685         assert_return(udev_device, -EINVAL);
 686
 687         r = sd_device_get_usec_since_initialized(udev_device->device, &ts);
 688         if (r < 0)
 689                 return_with_errno(0, r);
 690
 691         return ts;
 692 }
 693
 694 /**
 695  * udev_device_get_sysattr_value:
 696  * @udev_device: udev device
 697  * @sysattr: attribute name
 698  *
 699  * The retrieved value is cached in the device. Repeated calls will return the same
 700  * value and not open the attribute again.
 701  *
 702  * Returns: the content of a sys attribute file, or #NULL if there is no sys attribute value.
 703  **/
 704 _public_ const char *udev_device_get_sysattr_value(struct udev_device *udev_device, const char *sysattr) {
 705         const char *value;
 706         int r;
 707
 708         assert_return_errno(udev_device, NULL, EINVAL);
 709
 710         r = sd_device_get_sysattr_value(udev_device->device, sysattr, &value);
 711         if (r < 0)
 712                 return_with_errno(NULL, r);
 713
 714         return value;
 715 }
 716
 717 /**
 718  * udev_device_set_sysattr_value:
 719  * @udev_device: udev device
 720  * @sysattr: attribute name
 721  * @value: new value to be set
 722  *
 723  * Update the contents of the sys attribute and the cached value of the device.
 724  *
 725  * Returns: Negative error code on failure or 0 on success.
 726  **/
 727 _public_ int udev_device_set_sysattr_value(struct udev_device *udev_device, const char *sysattr, const char *value) {
 728         int r;
 729
 730         assert_return(udev_device, -EINVAL);
 731
 732         r = sd_device_set_sysattr_value(udev_device->device, sysattr, value);
 733         if (r < 0)
 734                 return r;
 735
 736         return 0;
 737 }
 738
 739 /**
 740  * udev_device_get_sysattr_list_entry:
 741  * @udev_device: udev device
 742  *
 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.
 746  *
 747  * Returns: the first entry of the property list
 748  **/
 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);
 751
 752         if (!udev_device->sysattrs_read) {
 753                 const char *sysattr;
 754
 755                 udev_list_cleanup(udev_device->sysattrs);
 756
 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);
 760
 761                 udev_device->sysattrs_read = true;
 762         }
 763
 764         return udev_list_get_entry(udev_device->sysattrs);
 765 }
 766
 767 /**
 768  * udev_device_get_is_initialized:
 769  * @udev_device: udev device
 770  *
 771  * Check if udev has already handled the device and has set up
 772  * device node permissions and context, or has renamed a network
 773  * device.
 774  *
 775  * This is only implemented for devices with a device node
 776  * or network interfaces. All other devices return 1 here.
 777  *
 778  * Returns: 1 if the device is set up. 0 otherwise.
 779  **/
 780 _public_ int udev_device_get_is_initialized(struct udev_device *udev_device) {
 781         int r;
 782
 783         assert_return(udev_device, -EINVAL);
 784
 785         r = sd_device_get_is_initialized(udev_device->device);
 786         if (r < 0)
 787                 return_with_errno(0, r);
 788
 789         return r;
 790 }
 791
 792 /**
 793  * udev_device_get_tags_list_entry:
 794  * @udev_device: udev device
 795  *
 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().
 800  *
 801  * Returns: the first entry of the tag list
 802  **/
 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);
 805
 806         if (device_get_tags_generation(udev_device->device) != udev_device->tags_generation ||
 807             !udev_device->tags_read) {
 808                 const char *tag;
 809
 810                 udev_list_cleanup(udev_device->tags);
 811
 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);
 815
 816                 udev_device->tags_read = true;
 817                 udev_device->tags_generation = device_get_tags_generation(udev_device->device);
 818         }
 819
 820         return udev_list_get_entry(udev_device->tags);
 821 }
 822
 823 /**
 824  * udev_device_has_tag:
 825  * @udev_device: udev device
 826  * @tag: tag name
 827  *
 828  * Check if a given device has a certain tag associated.
 829  *
 830  * Returns: 1 if the tag is found. 0 otherwise.
 831  **/
 832 _public_ int udev_device_has_tag(struct udev_device *udev_device, const char *tag) {
 833         assert_return(udev_device, 0);
 834
 835         return sd_device_has_tag(udev_device->device, tag) > 0;
 836 }