sd_bus_get_fd

systemd
sd_bus_get_fd 3
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

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

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