sd_device_enumerator_new(3)

.SH "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

.SH "SYNOPSIS"

#include <systemd/sd-device.h>

.HP 696u int sd_device_enumerator_new(sd_device_enumerator **ret);

.HP 1128u sd_device_enumerator* sd_device_enumerator_ref(sd_device_enumerator *enumerator);

.HP 1176u sd_device_enumerator* sd_device_enumerator_unref(sd_device_enumerator *enumerator);

.HP 792u void sd_device_enumerator_unrefp(sd_device_enumerator **enumerator);

.SH "DESCRIPTION"

.PP The sd_device_enumerator family of functions provides a way to iterate over devices recognized by systemd-udevd(8). The enumerator allows filtering and matching devices by subsystem, properties and other attributes.

.PP sd_device_enumerator_new() creates a new device enumerator object and stores the result in the pointer referenced by ret. Returns 0 on success, or a negative errno-style error code on failure.

.PP sd_device_enumerator_ref() increases the reference count of the specified enumerator by one.

.PP sd_device_enumerator_unref() decreases the reference count of the enumerator by one. When the reference count reaches 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.

.PP sd_device_enumerator_unrefp() is similar to sd_device_enumerator_unref() but 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. Use a declaration like the following, in order to allocate a 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));


  ...
}

.PP sd_device_enumerator_ref() and sd_device_enumerator_unref() execute no operation if the enumerator is NULL. sd_device_enumerator_unrefp() will first dereference its argument, which must not be NULL, and will execute no operation if that is NULL.

.SH "RETURN VALUE"

.PP sd_device_enumerator_new() returns 0 on success or a negative errno-style error code on failure.

.PP sd_device_enumerator_ref() always returns the enumerator pointer.

.PP sd_device_enumerator_unref() always returns NULL.

.SS "Errors"

.PP Returned errors may indicate the following problems:

.PP -ENOMEM

/* 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;
}