NAME

       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

SYNOPSIS

       #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);

DESCRIPTION

       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.

RETURN VALUE

       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.

   Errors
       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.

NOTES

       These APIs are implemented as a shared library, which can be compiled and linked to with
       the libsystemd pkg-config(1) file.

SEE ALSO

       systemd(1), sd-bus(3), sd_bus_set_fd(3), sd_bus_process(3), sd_bus_attach_event(3),
       sd_bus_wait(3), poll(3)