SD_DEVICE_ENUMERATOR_UNREFP(3)

📦
version 261.3 · 11 versions
, in ubuntu stonking

💖 sd_device_enumerator_new — the manual page, but make it cute 💖

okay bestie, welcome to the sd_device_enumerator_new(3) page from the systemd manuals — section 3 of the manual, iykyk. it's giving "how do i make, copy, and yeet a device enumerator object" and honestly? essential. let's go 🦋

✨ NAME ✨

sd_device_enumerator_new, sd_device_enumerator_ref, sd_device_enumerator_unref, sd_device_enumerator_unrefp — create, reference, and release a device enumerator object. that's the whole vibe 🎀

🌸 SYNOPSIS 🌸

#include <systemd/sd-device.h>

int sd_device_enumerator_new(sd_device_enumerator **ret);

sd_device_enumerator*
                                               sd_device_enumerator_ref(sd_device_enumerator *enumerator);

sd_device_enumerator*
                                                 sd_device_enumerator_unref(sd_device_enumerator *enumerator);

void sd_device_enumerator_unrefp(sd_device_enumerator **enumerator);

💅 DESCRIPTION 💅

so the sd_device_enumerator family of functions? it's literally your way to iterate over devices that are recognized by systemd-udevd(8). and the enumerator is gonna let you filter and match devices by subsystem, properties and other attributes. it's lowkey the main character of device listing ✨

  • sd_device_enumerator_new() — creates a brand new device enumerator object and stores the result in the pointer that ret references. returns 0 on success, or a negative errno-style error code if it flops. 🫶
  • sd_device_enumerator_ref() — bumps the reference count of the specified enumerator up by one. keeping it alive, keeping it iconic.
  • sd_device_enumerator_unref() — drops the reference count of the enumerator by one. and like… when the reference count hits zero, the enumerator object is destroyed and cannot be used anymore 💀 so further calls to sd_device_enumerator_unref() or sd_device_enumerator_unrefp() are illegal. not "frowned upon" — illegal. don't do it. 🙈
  • sd_device_enumerator_unrefp() — similar to sd_device_enumerator_unref() but it takes a pointer to a pointer to an sd_device_enumerator 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, ngl.

use a declaration like the following, in order to allocate an sd_device_enumerator object that is freed automatically as the code block is left:

{
  __attribute__((cleanup(sd_device_enumerator_unrefp))) sd_device_enumerator *enumerator = NULL;
  int r;
  ...
  r = sd_device_enumerator_new(&enumerator);
  if (r < 0)
    fprintf(stderr, "Failed to allocate sd_device_enumerator: %s\n", strerror(-r));
  ...
}

and the null-safety tea ☕: sd_device_enumerator_ref() and sd_device_enumerator_unref() execute no operation if the enumerator is NULL. meanwhile sd_device_enumerator_unrefp() will first dereference its argument, which must not be NULL, and will execute no operation if that is NULL. so it's a pointer-to-a-pointer and the outer one has to actually point somewhere, bestie. no cap. 🎯

🌈 RETURN VALUE 🌈

  • sd_device_enumerator_new() returns 0 on success or a negative errno-style error code on failure.
  • sd_device_enumerator_ref() always returns the enumerator pointer. always. every time. slay.
  • sd_device_enumerator_unref() always returns NULL.

💀 Errors 💀

returned errors may indicate the following problems:

  • -ENOMEM — memory allocation failed. the malloc said no. 😭
  • -EINVAL — the argument is invalid. bestie what did you even pass in. 🙈

🌟 EXAMPLE 🌟

Example 1. Using sd_device_enumerator_new()

/* SPDX-License-Identifier: MIT-0 */

#include <stdio.h>
#include <systemd/sd-device.h>

int main(void) {
    sd_device_enumerator *enumerator;
    int r;

    r = sd_device_enumerator_new(&enumerator);
    if (r < 0) {
        fprintf(stderr, "Failed to create enumerator: %s\n", strerror(-r));
        return 1;
    }

    sd_device_enumerator_ref(enumerator);
    sd_device_enumerator_unref(enumerator);

    sd_device_enumerator_unref(enumerator);

    return 0;
}

look at that cleanup. ref once, unref twice, balance restored. the way that reference counting ate. 👑

🦋 HISTORY 🦋

sd_device_enumerator_new(), sd_device_enumerator_ref(), sd_device_enumerator_unref(), and sd_device_enumerator_unrefp() were added in version 240. vintage but still iconic. ⭐

🎀 SEE ALSO 🎀

go read those next, they're the friend group. 💜

🫶 NOTES 🫶

  1. Clean-up Variable Attribute https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html

and that's the whole page, bestie! this was from systemd 261.3, and it's the SD_DEVICE_ENUMERATOR_NEW(3) manual page — go forth and enumerate responsibly, mwah 💅💖✨

📦 where this page comes from