Line events handling

Structures and functions allowing to poll lines for events and read them, both for individual lines as well as in bulk. More...

Collaboration diagram for Line events handling:

Data Structures
struct	gpiod_line_event
	Structure holding event info. More...

Enumerations
enum	{ GPIOD_LINE_EVENT_RISING_EDGE = 1, GPIOD_LINE_EVENT_FALLING_EDGE }
	Event types. More...

Functions
int	gpiod_line_event_wait (struct gpiod_line *line, const struct timespec *timeout) GPIOD_API
	Wait for an event on a single line. More...
int	gpiod_line_event_wait_bulk (struct gpiod_line_bulk *bulk, const struct timespec *timeout, struct gpiod_line_bulk *event_bulk) GPIOD_API
	Wait for events on a set of lines. More...
int	gpiod_line_event_read (struct gpiod_line *line, struct gpiod_line_event *event) GPIOD_API
	Read next pending event from the GPIO line. More...
int	gpiod_line_event_read_multiple (struct gpiod_line *line, struct gpiod_line_event *events, unsigned int num_events) GPIOD_API
	Read up to a certain number of events from the GPIO line. More...
int	gpiod_line_event_get_fd (struct gpiod_line *line) GPIOD_API
	Get the event file descriptor. More...
int	gpiod_line_event_read_fd (int fd, struct gpiod_line_event *event) GPIOD_API
	Read the last GPIO event directly from a file descriptor. More...
int	gpiod_line_event_read_fd_multiple (int fd, struct gpiod_line_event *events, unsigned int num_events) GPIOD_API
	Read up to a certain number of events directly from a file descriptor. More...

Detailed Description

Structures and functions allowing to poll lines for events and read them, both for individual lines as well as in bulk.

Also contains functions for retrieving the associated file descriptors and operate on them for easy integration with standard unix interfaces.

Enumeration Type Documentation

anonymous enum

anonymous enum

Event types.

Enumerator
GPIOD_LINE_EVENT_RISING_EDGE	Rising edge event.
GPIOD_LINE_EVENT_FALLING_EDGE	Falling edge event.

Definition at line 1473 of file gpiod.h.

Function Documentation

gpiod_line_event_get_fd()

int gpiod_line_event_get_fd

(

struct gpiod_line *

line

)

Get the event file descriptor.

Parameters

line	GPIO line object.

Returns

Number of the event file descriptor or -1 if the user tries to retrieve the descriptor from a line that wasn't configured for event monitoring.

Users may want to poll the event file descriptor on their own. This routine allows to access it.

gpiod_line_event_read()

int gpiod_line_event_read	(	struct gpiod_line *	line,
		struct gpiod_line_event *	event
	)

Read next pending event from the GPIO line.

Parameters

line	GPIO line object.
event	Buffer to which the event data will be copied.

Returns

0 if the event was read correctly, -1 on error.

Note

This function will block if no event was queued for this line.

gpiod_line_event_read_fd()

int gpiod_line_event_read_fd	(	int	fd,
		struct gpiod_line_event *	event
	)

Read the last GPIO event directly from a file descriptor.

Parameters

fd	File descriptor.
event	Buffer in which the event data will be stored.

Returns

0 if the event was read correctly, -1 on error.

Users who directly poll the file descriptor for incoming events can also directly read the event data from it using this routine. This function translates the kernel representation of the event to the libgpiod format.

gpiod_line_event_read_fd_multiple()

int gpiod_line_event_read_fd_multiple	(	int	fd,
		struct gpiod_line_event *	events,
		unsigned int	num_events
	)

Read up to a certain number of events directly from a file descriptor.

Parameters

fd	File descriptor.
events	Buffer to which the event data will be copied. Must hold at least the amount of events specified in num_events.
num_events	Specifies how many events can be stored in the buffer.

Returns

On success returns the number of events stored in the buffer, on failure -1 is returned.

gpiod_line_event_read_multiple()

int gpiod_line_event_read_multiple	(	struct gpiod_line *	line,
		struct gpiod_line_event *	events,
		unsigned int	num_events
	)

Read up to a certain number of events from the GPIO line.

Parameters

line	GPIO line object.
events	Buffer to which the event data will be copied. Must hold at least the amount of events specified in num_events.
num_events	Specifies how many events can be stored in the buffer.

Returns

On success returns the number of events stored in the buffer, on failure -1 is returned.

gpiod_line_event_wait()

int gpiod_line_event_wait	(	struct gpiod_line *	line,
		const struct timespec *	timeout
	)

Wait for an event on a single line.

Parameters

line	GPIO line object.
timeout	Wait time limit.

Returns

0 if wait timed out, -1 if an error occurred, 1 if an event occurred.

gpiod_line_event_wait_bulk()

int gpiod_line_event_wait_bulk	(	struct gpiod_line_bulk *	bulk,
		const struct timespec *	timeout,
		struct gpiod_line_bulk *	event_bulk
	)

Wait for events on a set of lines.

Parameters

bulk	Set of GPIO lines to monitor.
timeout	Wait time limit.
event_bulk	Bulk object in which to store the line handles on which events occurred. Can be NULL.

Returns

0 if wait timed out, -1 if an error occurred, 1 if at least one event occurred.