SD\_DEVICE\_ENUMERATOR\_NEW(3) sd\_device\_enumerator\_new 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)](/man/os/systemd/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**

Memory allocation failed.

.RE  
.PP **-EINVAL**

The argument is invalid.

.RE

.SH "EXAMPLE"

.PP **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;
}
```

.SH "HISTORY"

.PP **sd\_device\_enumerator\_new()**, **sd\_device\_enumerator\_ref()**, **sd\_device\_enumerator\_unref()**, and **sd\_device\_enumerator\_unrefp()** were added in version 240.

.SH "SEE ALSO"

.PP [**sd\_device\_ref**(3)](/man/os/systemd/sd_device_ref.3), [**sd\_device\_enumerator\_add\_match\_parent**(3)](/man/os/systemd/sd_device_enumerator_add_match_parent.3)

# [NOTES](#NOTES)

1\.

Clean-up Variable Attribute

https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html

systemd 262.2

---

Document: sd_device_enumerator_new(3) from systemd 262.2-r1 (Chainguard OS)
Source: https://github.com/systemd/systemd