sd_bus_get_fd, sd_bus_get_events, sd_bus_get_timeout — Get the file descriptor, I/O events and time-out to wait for from a message bus object
#include <systemd/sd-bus.h>
int sd_bus_get_fd( | sd_bus *bus) ; |
int sd_bus_get_events( | sd_bus *bus) ; |
int sd_bus_get_timeout( | sd_bus *bus, |
uint64_t *timeout_usec) ; |
sd_bus_get_fd()
returns the file descriptor used to communicate from a message bus
object. This descriptor can be used with poll(3) or a similar
function to wait for I/O events on the specified bus connection object. If the bus object was configured with the
sd_bus_set_fd(3) function, then
the input_fd
file descriptor used in that call is returned.
sd_bus_get_events()
returns the I/O events to wait for, suitable for passing to
poll()
or a similar call. Returns a combination of POLLIN
,
POLLOUT
, … events, or negative on error.
sd_bus_get_timeout()
returns the time-out in µs to pass to to
poll()
or a similar call when waiting for events on the specified bus connection. The returned
time-out may be zero, in which case a subsequent I/O polling call should be invoked in non-blocking mode. The
returned timeout may be UINT64_MAX
in which case the I/O polling call may block indefinitely,
without any applied time-out. Note that the returned time-out should be considered only a maximum sleeping time. It
is permissible (and even expected) that shorter time-outs are used by the calling program, in case other event
sources are polled in the same event loop. Note that the returned time-value is relative and specified in
microseconds. When converting this value in order to pass it as third argument to poll()
(which expects milliseconds), care should be taken to use a division that rounds up to ensure the I/O polling
operation doesn't sleep for shorter than necessary, which might result in unintended busy looping (alternatively,
use ppoll(3)
instead of plain poll()
, which understands time-outs with nano-second granularity).
These three functions are useful to hook up a bus connection object with an external or manual event loop
involving poll()
or a similar I/O polling call. Before each invocation of the I/O polling
call, all three functions should be invoked: the file descriptor returned by sd_bus_get_fd()
should be polled for the events indicated by sd_bus_get_events()
, and the I/O call should
block for that up to the time-out returned by sd_bus_get_timeout()
. After each I/O polling
call the bus connection needs to process incoming or outgoing data, by invoking
sd_bus_process(3).
Note that these function are only one of three supported ways to implement I/O event handling for bus connections. Alternatively use sd_bus_attach_event(3) to attach a bus connection to an sd-event(3) event loop. Or use sd_bus_wait(3) as a simple synchronous, blocking I/O waiting call.
sd_bus_get_fd()
returns the file descriptor used for communication, or a negative
errno
-style error code on error.
sd_bus_get_events()
returns the I/O event mask to use for I/O event watching, or a
negative errno
-style error code on error.
sd_bus_get_timeout()
returns zero or positive on success, or a negative
errno
-style error code on error.
Returned errors may indicate the following problems:
-EINVAL
¶An invalid bus object was passed.
-ECHILD
¶The bus connection was allocated in a parent process and is being reused in a child
process after fork()
.
-ENOTCONN
¶The bus connection has been terminated.
-EPERM
¶Two distinct file descriptors were passed for input and output using
sd_bus_set_fd()
, which sd_bus_get_fd()
cannot
return.
These APIs are implemented as a shared
library, which can be compiled and linked to with the
libsystemd
pkg-config(1)
file.