libgpiotools API

group gpiotools

Reusable chip and line resolution helpers used by the suite of GPIO command-line tools. These functions allow users to build their own programs on top of libgpiod using the same high-level abstractions as the gpio-tools.

Unlike libgpiod core C API, public structures exposed by libgpiotools are not opaque by design. The goal is to allow easy access to members without providing a large number of very similar accessors. We leave some padding for potential future extensions.

Error handling: functions typically return negative integer values or NULL pointers on failure and set errno to indicate the cause unless otherwise noted.

Functions

char *gpiotools_chip_path_lookup(const char *id)

Look up the path to a GPIO chip device.

Parameters:

id – Chip identifier: a number (“0”), a name (“gpiochip0”), or a path (“/dev/gpiochip0”).

Returns:

Pointer to a newly allocated string containing the filesystem path to the GPIO chip or NULL on failure. The user is responsible for calling free() on the pointer returned on success.

int gpiotools_chip_paths(const char *id, char ***paths_ptr)

Get the paths of GPIO chip devices matching an identifier.

Parameters:

  • id – Chip identifier, or NULL to return all chips.

  • paths_ptr – On success, set to a newly allocated array of path strings. The caller must free() each element and the array itself.

Returns:

Number of chips found (0 if none), or negative errno on error.

int gpiotools_all_chip_paths(char ***paths_ptr)

Get the paths of all GPIO chip devices on the system.

Parameters:

paths_ptr – On success, set to a newly allocated array of path strings. The caller must free() each element and the array itself.

Returns:

Number of chips found (0 if none), or negative errno on error.

struct gpiotools_line_resolver *gpiotools_resolver_init(int num_lines, char **lines, int num_chips, bool strict, bool by_name)

Allocate and initialise a line resolver.

Parameters:

  • num_lines – Number of lines to resolve.

  • lines – Array of line identifiers (names or offset strings).

  • num_chips – Number of chips to allocate space for.

  • strict – If true, perform an exhaustive search to verify that line names are unique.

  • by_name – If true, treat all identifiers as names; if false, try to parse them as numeric offsets first.

Returns:

Pointer to the new resolver, or NULL on failure.

bool gpiotools_resolve_lines_by_offset(struct gpiotools_line_resolver *resolver, unsigned int num_lines)

Resolve lines by numeric offset.

Marks lines whose identifier was successfully parsed as a numeric offset as resolved. Only applies to the first chip (chip_num == 0).

Parameters:

  • resolver – Resolver to update.

  • num_lines – Number of lines on the chip.

Returns:

True if any line was resolved, false otherwise.

bool gpiotools_resolve_done(struct gpiotools_line_resolver *resolver)

Check whether line resolution is complete.

In non-strict mode, resolution is considered done when all requested lines have been found. In strict mode this always returns false so that the caller performs an exhaustive search.

Parameters:

resolver – Resolver to check.

Returns:

True if resolution is complete, false otherwise.

struct gpiotools_line_resolver *gpiotools_resolve_lines(int num_lines, char **lines, const char *chip_id, bool strict, bool by_name)

Resolve line names or offsets to GPIO lines on the system.

Parameters:

  • num_lines – Number of lines to resolve.

  • lines – Array of line identifiers (names or offset strings).

  • chip_id – Chip identifier to restrict the search, or NULL to search all chips.

  • strict – If true, verify that line names are unique across all chips.

  • by_name – If true, treat all identifiers as names.

Returns:

Pointer to the populated resolver, or NULL on error with errno set.

void gpiotools_free_line_resolver(struct gpiotools_line_resolver *resolver)

Free a line resolver and all memory it owns.

Parameters:

resolver – Resolver to free. May be NULL.

int gpiotools_get_line_offsets_and_values(struct gpiotools_line_resolver *resolver, int chip_num, unsigned int *offsets, enum gpiod_line_value *values)

Extract offsets and optionally values for lines on a specific chip.

Note

offsets and values must be large enough to hold the number of lines stored in the resolver

Parameters:

  • resolver – Resolver containing the resolved lines.

  • chip_num – Index of the chip to query.

  • offsets – Pre-allocated array to receive the line offsets.

  • values – Pre-allocated array to receive the line values, or NULL.

Returns:

Number of lines belonging to the specified chip.

const char *gpiotools_get_chip_name(struct gpiotools_line_resolver *resolver, int chip_num)

Get the name of a chip referenced by the resolver.

Parameters:

  • resolver – Resolver containing the chip.

  • chip_num – Index of the chip.

Returns:

Pointer to the chip name string owned by the resolver.

const char *gpiotools_get_line_name(struct gpiotools_line_resolver *resolver, int chip_num, unsigned int offset)

Get the name of a resolved line.

Parameters:

  • resolver – Resolver containing the line.

  • chip_num – Index of the chip the line belongs to.

  • offset – Offset of the line on the chip.

Returns:

Pointer to the line name string owned by the resolver, or NULL if the line has no name.

void gpiotools_set_line_values(struct gpiotools_line_resolver *resolver, int chip_num, enum gpiod_line_value *values)

Update line values stored in the resolver for a specific chip.

Parameters:

  • resolver – Resolver to update.

  • chip_num – Index of the chip whose lines should be updated.

  • values – Array of values to store, one per line on the chip in the order they appear in the resolver.

struct gpiotools_resolved_line
#include <gpiotools.h>

Descriptor for a single resolved GPIO line.

Public Members

const char *id

Identifier string from the command line.

int id_as_offset

ID parsed as an integer offset, or -1 if the line must be resolved by name.

bool resolved

True once the line has been located on a chip.

bool not_unique

True if strict mode found the name on more than one chip.

struct gpiod_line_info *info

Line info object; only valid once resolved.

int chip_num

Index of the owning chip in the resolver’s chips array.

unsigned int offset

Offset of the line on its chip.

int value

Line value used by gpioget/gpioset.

struct gpiotools_resolved_chip
#include <gpiotools.h>

Descriptor for a single GPIO chip referenced by a resolver.

Public Members

struct gpiod_chip_info *info

Chip info object.

char *path

Path to the chip device file.

struct gpiotools_line_resolver
#include <gpiotools.h>

Resolver mapping requested line names or offsets to GPIO lines.

Public Members

int num_chips

Number of chips the lines span; also the number of entries in chips.

int num_lines

Number of entries in lines.

int num_found

Number of lines that have been found so far.

bool strict

If true, perform an exhaustive search to verify line name uniqueness.

struct gpiotools_resolved_chip *chips

Array of chip descriptors for the chips that own the requested lines.

struct gpiotools_resolved_line lines[]

Flexible array of line descriptors for the requested lines.