sd_device_ref(3) — Linux manual page

NAME \| SYNOPSIS \| RETURN VALUE \| HISTORY \| NOTES \| COLOPHON

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
           https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html

COLOPHON top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have a
       bug report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2025-08-11.)  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
       man-pages@man7.org

systemd 258~rc2                                          SD_DEVICE_REF(3)

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