'\" t
.TH "SD_DEVICE_ENUMERATOR_GET_DEVICE_FIRST" "3" "" "systemd 258" "sd_device_enumerator_get_device_first"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd_device_enumerator_get_device_first, sd_device_enumerator_get_device_next, sd_device_enumerator_get_subsystem_first, sd_device_enumerator_get_subsystem_next \- Enumerates devices and get the first or next device\&.
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-device\&.h>
.fi
.ft
.HP \w'sd_device\ *sd_device_enumerator_get_device_first('u
.BI "sd_device *sd_device_enumerator_get_device_first(sd_device_enumerator\ *" "enumerator" ");"
.HP \w'sd_device\ *sd_device_enumerator_get_device_next('u
.BI "sd_device *sd_device_enumerator_get_device_next(sd_device_enumerator\ *" "enumerator" ");"
.HP \w'sd_device\ *sd_device_enumerator_get_subsystem_first('u
.BI "sd_device *sd_device_enumerator_get_subsystem_first(sd_device_enumerator\ *" "enumerator" ");"
.HP \w'sd_device\ *sd_device_enumerator_get_subsystem_next('u
.BI "sd_device *sd_device_enumerator_get_subsystem_next(sd_device_enumerator\ *" "enumerator" ");"
.SH "DESCRIPTION"
.PP
The
\fBsd_device_enumerator_get_device_first()\fR
function enumerates all matching devices under
/sys/bus/\fISUBSYSTEM\fR/devices/
and
/sys/class/\fISUBSYSTEM\fR/devices/, and returns a pointer to the first
\fBsd_device\fR
object\&. If no devices are found,
\fBNULL\fR
is returned\&.
.PP
The
\fBsd_device_enumerator_get_device_next()\fR
function returns the pointer to the next
\fBsd_device\fR
from the
\fIenumerator\fR\&. It should be called after
\fBsd_device_enumerator_get_device_first()\fR
or after a previous call to this function\&. If no more devices are available,
\fBNULL\fR
is returned\&.
.PP
The
\fBsd_device_enumerator_get_subsystem_first()\fR
function enumerates all matching subsystem devices in
/sys/module/,
/sys/bus/, and
/sys/bus/\fISUBSYSTEM\fR/drivers/
(such as
/sys/bus/pci/drivers/)\&. It returns a pointer to the first
\fBsd_device\fR
object\&. If no devices are found
\fBNULL\fR
is returned\&. Note that this does
\fInot\fR
enumerate devices provided by
\fBsd_device_enumerator_get_device_first/next()\fR\&. Hence, e\&.g\&.
/sys/bus/pci/,
/sys/bus/pci/drivers/ahci/
and so on are enumerated, but
/sys/bus/pci/devices/0000:00:00\&.0/
and so on are not\&.
.PP
The
\fBsd_device_enumerator_get_subsystem_next()\fR
function returns the next subsystem device from the enumerator\&. It should be called after
\fBsd_device_enumerator_get_subsystem_first()\fR
or after a previous call to this function\&. If no more subsystem devices are available,
\fBNULL\fR
is returned\&.
.SH "RETURN VALUE"
.PP
On success, these functions return a pointer to an
\fBsd_device\fR
object\&. On failure or when no more devices are available,
\fBNULL\fR
is returned\&. The returned pointers are owned by the enumerator and should not be freed by the caller\&.
.SH "HISTORY"
.PP
\fBsd_device_enumerator_get_device_first()\fR,
\fBsd_device_enumerator_get_device_next()\fR,
\fBsd_device_enumerator_get_subsystem_first()\fR, and
\fBsd_device_enumerator_get_subsystem_next()\fR
were introduced in systemd version 240\&.
.SH "SEE ALSO"
.PP
\fBsd_device_enumerator_new\fR(3), \fBsd_device_enumerator_add_match_parent\fR(3), \fBsd_device_ref\fR(3)