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

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

       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.

       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.

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

       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.

       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));
             ...
           }

       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.

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.

       sd_device_enumerator_unref() always returns NULL.

   Errors
       Returned errors may indicate the following problems:

       -ENOMEM
           Memory allocation failed.

       -EINVAL
           The argument is invalid.

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

HISTORY

       sd_device_enumerator_new(), sd_device_enumerator_ref(), sd_device_enumerator_unref(), and
       sd_device_enumerator_unrefp() were added in version 240.

SEE ALSO

       sd_device_ref(3), sd_device_enumerator_add_match_parent(3)

NOTES

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

systemd 257.7                                                                        SD_DEVICE_ENUMERATOR_NEW(3)