libgpiod  0.3.2
Data Structures | Macros | Enumerations | Functions
Iterators for GPIO chips and lines

These functions and data structures allow easy iterating over GPIO chips and lines. More...

Data Structures

struct  gpiod_line_iter
 GPIO line iterator structure. More...
 

Macros

#define gpiod_foreach_chip(iter, chip)
 Iterate over all gpiochip present in the system. More...
 
#define gpiod_foreach_chip_noclose(iter, chip)
 Iterate over all gpiochip present in the system without closing them. More...
 
#define GPIOD_LINE_ITER_INITIALIZER(chip)   { 0, (chip), GPIOD_LINE_ITER_INIT }
 Static initializer for line iterators. More...
 
#define gpiod_foreach_line(iter, line)
 Iterate over all GPIO lines of a single chip. More...
 

Enumerations

enum  { GPIOD_LINE_ITER_INIT = 0, GPIOD_LINE_ITER_DONE, GPIOD_LINE_ITER_ERR }
 Possible states of a line iterator. More...
 

Functions

struct gpiod_chip_iter * gpiod_chip_iter_new (void) GPIOD_API
 Create a new gpiochip iterator. More...
 
void gpiod_chip_iter_free (struct gpiod_chip_iter *iter) GPIOD_API
 Release all resources allocated for the gpiochip iterator and close the most recently opened gpiochip (if any). More...
 
void gpiod_chip_iter_free_noclose (struct gpiod_chip_iter *iter) GPIOD_API
 Release all resources allocated for the gpiochip iterator but don't close the most recently opened gpiochip (if any). More...
 
struct gpiod_chip * gpiod_chip_iter_next (struct gpiod_chip_iter *iter) GPIOD_API
 Get the next gpiochip handle. More...
 
struct gpiod_chip * gpiod_chip_iter_next_noclose (struct gpiod_chip_iter *iter) GPIOD_API
 Get the next gpiochip handle without closing the previous one. More...
 
bool gpiod_chip_iter_done (struct gpiod_chip_iter *iter) GPIOD_API
 Check if we're done iterating over gpiochips on this iterator. More...
 
bool gpiod_chip_iter_err (struct gpiod_chip_iter *iter) GPIOD_API
 Check if we've encountered an error condition while opening a gpiochip. More...
 
const char * gpiod_chip_iter_failed_chip (struct gpiod_chip_iter *iter) GPIOD_API
 Get the name of the gpiochip that we failed to access. More...
 
static void gpiod_line_iter_init (struct gpiod_line_iter *iter, struct gpiod_chip *chip)
 Initialize a GPIO line iterator. More...
 
struct gpiod_line * gpiod_line_iter_next (struct gpiod_line_iter *iter) GPIOD_API
 Get the next GPIO line handle. More...
 
static bool gpiod_line_iter_done (const struct gpiod_line_iter *iter)
 Check if we're done iterating over lines on this iterator. More...
 
static bool gpiod_line_iter_err (const struct gpiod_line_iter *iter)
 Check if we've encountered an error condition while retrieving info for a line. More...
 
static unsigned int gpiod_line_iter_last_offset (const struct gpiod_line_iter *iter)
 Get the offset of the last line we tried to open. More...
 

Detailed Description

These functions and data structures allow easy iterating over GPIO chips and lines.

Macro Definition Documentation

◆ gpiod_foreach_chip

#define gpiod_foreach_chip (   iter,
  chip 
)
Value:
for ((chip) = gpiod_chip_iter_next(iter); \
(chip) = gpiod_chip_iter_next(iter))
bool gpiod_chip_iter_done(struct gpiod_chip_iter *iter) GPIOD_API
Check if we're done iterating over gpiochips on this iterator.
struct gpiod_chip * gpiod_chip_iter_next(struct gpiod_chip_iter *iter) GPIOD_API
Get the next gpiochip handle.

Iterate over all gpiochip present in the system.

Parameters
iterAn initialized GPIO chip iterator.
chipPointer to a GPIO chip handle. On each iteration the newly opened chip handle is assigned to this argument.

The user must not close the GPIO chip manually - instead the previous chip handle is closed automatically on the next iteration. The last chip to be opened is closed internally by gpiod_chip_iter_free().

Definition at line 933 of file gpiod.h.

◆ gpiod_foreach_chip_noclose

#define gpiod_foreach_chip_noclose (   iter,
  chip 
)
Value:
for ((chip) = gpiod_chip_iter_next_noclose(iter); \
bool gpiod_chip_iter_done(struct gpiod_chip_iter *iter) GPIOD_API
Check if we're done iterating over gpiochips on this iterator.
struct gpiod_chip * gpiod_chip_iter_next_noclose(struct gpiod_chip_iter *iter) GPIOD_API
Get the next gpiochip handle without closing the previous one.

Iterate over all gpiochip present in the system without closing them.

Parameters
iterAn initialized GPIO chip iterator.
chipPointer to a GPIO chip handle. On each iteration the newly opened chip handle is assigned to this argument.

The user must close the GPIO chip manually after use, until then, the chip remains open. Free the iterator by calling gpiod_chip_iter_free_noclose to avoid closing the last chip automatically.

Definition at line 948 of file gpiod.h.

◆ gpiod_foreach_line

#define gpiod_foreach_line (   iter,
  line 
)
Value:
for ((line) = gpiod_line_iter_next(iter); \
(line) = gpiod_line_iter_next(iter))
static bool gpiod_line_iter_done(const struct gpiod_line_iter *iter)
Check if we're done iterating over lines on this iterator.
Definition: gpiod.h:1042
struct gpiod_line * gpiod_line_iter_next(struct gpiod_line_iter *iter) GPIOD_API
Get the next GPIO line handle.

Iterate over all GPIO lines of a single chip.

Parameters
iterAn initialized GPIO line iterator.
linePointer to a GPIO line handle - on each iteration, the next GPIO line will be assigned to this argument.

Definition at line 1077 of file gpiod.h.

◆ GPIOD_LINE_ITER_INITIALIZER

#define GPIOD_LINE_ITER_INITIALIZER (   chip)    { 0, (chip), GPIOD_LINE_ITER_INIT }

Static initializer for line iterators.

Parameters
chipThe gpiochip object whose lines we want to iterate over.

Definition at line 1013 of file gpiod.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Possible states of a line iterator.

Enumerator
GPIOD_LINE_ITER_INIT 

Line iterator is initiated or iterating over lines.

GPIOD_LINE_ITER_DONE 

Line iterator is done with all lines on this chip.

GPIOD_LINE_ITER_ERR 

There was an error retrieving info for a line.

Definition at line 985 of file gpiod.h.

Function Documentation

◆ gpiod_chip_iter_done()

bool gpiod_chip_iter_done ( struct gpiod_chip_iter *  iter)

Check if we're done iterating over gpiochips on this iterator.

Parameters
iterThe gpiochip iterator object.
Returns
True if we've iterated over all chips, false otherwise.

◆ gpiod_chip_iter_err()

bool gpiod_chip_iter_err ( struct gpiod_chip_iter *  iter)

Check if we've encountered an error condition while opening a gpiochip.

Parameters
iterThe gpiochip iterator object.
Returns
True if there was an error opening a gpiochip device file, false otherwise.

◆ gpiod_chip_iter_failed_chip()

const char* gpiod_chip_iter_failed_chip ( struct gpiod_chip_iter *  iter)

Get the name of the gpiochip that we failed to access.

Parameters
iterThe gpiochip iterator object.
Returns
If gpiod_chip_iter_iserr() returned true, this function returns a pointer to the name of the gpiochip that we failed to access. If there was no error this function returns NULL.

NOTE: this function will return NULL if the internal memory allocation fails.

◆ gpiod_chip_iter_free()

void gpiod_chip_iter_free ( struct gpiod_chip_iter *  iter)

Release all resources allocated for the gpiochip iterator and close the most recently opened gpiochip (if any).

Parameters
iterThe gpiochip iterator object.

◆ gpiod_chip_iter_free_noclose()

void gpiod_chip_iter_free_noclose ( struct gpiod_chip_iter *  iter)

Release all resources allocated for the gpiochip iterator but don't close the most recently opened gpiochip (if any).

Parameters
iterThe gpiochip iterator object.

Users may want to break the loop when iterating over gpiochips and keep the most recently opened chip active while freeing the iterator data. This routine enables that.

◆ gpiod_chip_iter_new()

struct gpiod_chip_iter* gpiod_chip_iter_new ( void  )

Create a new gpiochip iterator.

Returns
Pointer to a new chip iterator object or NULL if an error occurred.

◆ gpiod_chip_iter_next()

struct gpiod_chip* gpiod_chip_iter_next ( struct gpiod_chip_iter *  iter)

Get the next gpiochip handle.

Parameters
iterThe gpiochip iterator object.
Returns
Pointer to an open gpiochip handle or NULL if the next chip can't be accessed.

Internally this routine scans the /dev/ directory, storing current state in the chip iterator structure, and tries to open the next /dev/gpiochipX device file. If an error occurs or no more chips are present, the function returns NULL.

◆ gpiod_chip_iter_next_noclose()

struct gpiod_chip* gpiod_chip_iter_next_noclose ( struct gpiod_chip_iter *  iter)

Get the next gpiochip handle without closing the previous one.

Parameters
iterThe gpiochip iterator object.
Returns
Pointer to an open gpiochip handle or NULL if the next chip can't be accessed.

Internally this routine scans the /dev/ directory, storing current state in the chip iterator structure, and tries to open the next /dev/gpiochipX device file. If an error occurs or no more chips are present, the function returns NULL. Note: The user is responsible for closing the chips after use.

◆ gpiod_line_iter_done()

static bool gpiod_line_iter_done ( const struct gpiod_line_iter iter)
inlinestatic

Check if we're done iterating over lines on this iterator.

Parameters
iterThe GPIO line iterator object.
Returns
True if we've iterated over all lines, false otherwise.

Definition at line 1042 of file gpiod.h.

References GPIOD_LINE_ITER_DONE, and gpiod_line_iter::state.

◆ gpiod_line_iter_err()

static bool gpiod_line_iter_err ( const struct gpiod_line_iter iter)
inlinestatic

Check if we've encountered an error condition while retrieving info for a line.

Parameters
iterThe GPIO line iterator object.
Returns
True if there was an error retrieving info about a GPIO line, false otherwise.

Definition at line 1054 of file gpiod.h.

References GPIOD_LINE_ITER_ERR, and gpiod_line_iter::state.

◆ gpiod_line_iter_init()

static void gpiod_line_iter_init ( struct gpiod_line_iter iter,
struct gpiod_chip *  chip 
)
inlinestatic

Initialize a GPIO line iterator.

Parameters
iterPointer to a GPIO line iterator.
chipThe gpiochip object whose lines we want to iterate over.

Definition at line 1020 of file gpiod.h.

References gpiod_line_iter::chip, GPIOD_API, GPIOD_LINE_ITER_INIT, gpiod_line_iter_next(), gpiod_line_iter::offset, and gpiod_line_iter::state.

◆ gpiod_line_iter_last_offset()

static unsigned int gpiod_line_iter_last_offset ( const struct gpiod_line_iter iter)
inlinestatic

Get the offset of the last line we tried to open.

Parameters
iterThe GPIO line iterator object.
Returns
The offset of the last line we tried to open - whether we failed or succeeded to do so.

Definition at line 1066 of file gpiod.h.

References gpiod_line_iter::offset.

◆ gpiod_line_iter_next()

struct gpiod_line* gpiod_line_iter_next ( struct gpiod_line_iter iter)

Get the next GPIO line handle.

Parameters
iterThe GPIO line iterator object.
Returns
Pointer to the next GPIO line handle or NULL if no more lines or and error occured.

Referenced by gpiod_line_iter_init().