|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | EXAMPLE | HISTORY | SEE ALSO | NOTES | COLOPHON |
|
|
|
SD_DEVICE...RATOR_NEW(3) sd_device_enumerator_newSD_DEVICE...RATOR_NEW(3)
sd_device_enumerator_new, sd_device_enumerator_ref,
sd_device_enumerator_unref, sd_device_enumerator_unrefp - Create,
reference, and release a device enumerator object
#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);
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.
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 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;
}
sd_device_enumerator_new(), sd_device_enumerator_ref(),
sd_device_enumerator_unref(), and sd_device_enumerator_unrefp()
were added in version 240.
sd_device_ref(3), sd_device_enumerator_add_match_parent(3)
1. Clean-up Variable Attribute
https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
This page is part of the systemd (systemd system and service
manager) project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a
bug report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
This page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2025-08-11. (At that
time, the date of the most recent commit that was found in the
repository was 2025-08-11.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
[email protected]
systemd 258~rc2 SD_DEVICE...RATOR_NEW(3)
Pages that refer to this page: sd_device_enumerator_add_match_parent(3), sd_device_enumerator_get_device_first(3), systemd.directives(7), systemd.index(7)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|