---
name: "sd_device_enumerator_unref"
section: "3"
platform: "linux"
package: "libsystemd-dev"
version: "257.13-1~deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/sd_device_enumerator_new"
---

# sd\_device\_enumerator\_unref(3)

Create, reference, and release a device enumerator object

Part of [sd\_device\_enumerator\_new(3)](/sd_device_enumerator_new/3.md).

## 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)](/systemd-udevd/8.md). 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_ref/3.md), [**sd\_device\_enumerator\_add\_match\_parent**(3)](/sd_device_enumerator_add_match_parent/3.md)

## NOTES

- 1\.

  Clean-up Variable Attribute

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