sd_device_ref(3) — Linux manual page


SD_DEVICE_REF(3)              sd_device_ref             SD_DEVICE_REF(3)

NAME         top

       sd_device_ref, sd_device_unref, sd_device_unrefp - Create or
       destroy references to a device object

SYNOPSIS         top

       #include <systemd/sd-device.h>

       sd_device* sd_device_ref(sd_device *device);

       sd_device* sd_device_unref(sd_device *device);

       void sd_device_unrefp(sd_device **device);

       sd_device_ref() increases the internal reference counter of
       device by one.

       sd_device_unref() decreases the internal reference counter of
       device by one. Once the reference count has dropped to zero,
       device is destroyed and cannot be used anymore, so further calls
       to sd_device_ref() or sd_device_unref() are illegal.

       sd_device_unrefp() is similar to sd_device_unref() but takes a
       pointer to a pointer to an sd_device object. This call is useful
       in conjunction with GCC's and LLVM's Clean-up Variable
       Attribute[1]. Note that this function is defined as an inline
       function. Use a declaration like the following, in order to
       allocate a device object that is freed automatically as the code
       block is left:

         __attribute__((cleanup(sd_device_unrefp))) sd_device *device = NULL;
         int r;
         r = sd_device_new_from_syspath(&device, "...");
         if (r < 0) {
           errno = -r;
           fprintf(stderr, "Failed to allocate device: %m\n");

       sd_device_ref() and sd_device_unref() execute no operation if the
       argument is NULL.  sd_device_unrefp() will first dereference its
       argument, which must not be NULL, and will execute no operation
       if that is NULL.

RETURN VALUE         top

       sd_device_ref() always returns the argument, and
       sd_device_unref() always returns NULL.

HISTORY         top

       sd_device_ref(), sd_device_unref(), and sd_device_unrefp() were
       added in version 251.

NOTES         top

        1. Clean-up Variable Attribute

COLOPHON         top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨⟩.  If you have
       a bug report for this manual page, see
       This page was obtained from the project's upstream Git repository
       ⟨⟩ on 2023-12-22.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2023-12-22.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

systemd 255                                             SD_DEVICE_REF(3)

Pages that refer to this page: sd-device(3)systemd.directives(7)systemd.index(7)