From b750101eb236130cf056c675997decbac904cc49 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 17:35:18 +0200 Subject: Adding upstream version 252.22. Signed-off-by: Daniel Baumann --- man/sd_bus_get_fd.xml | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 man/sd_bus_get_fd.xml (limited to 'man/sd_bus_get_fd.xml') diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml new file mode 100644 index 0000000..a8a1615 --- /dev/null +++ b/man/sd_bus_get_fd.xml @@ -0,0 +1,177 @@ + + + + + + + + + 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 timeout 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 + poll3 + 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() 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 timeout in µs to pass to + poll() or a similar call when waiting for events on the specified bus + connection. The returned timeout 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 timeout. Note that the returned timeout should be considered only a + maximum sleeping time. It is permissible (and even expected) that shorter timeouts 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 absolute, based of CLOCK_MONOTONIC and specified + in microseconds. When converting this value in order to pass it as third argument to + poll() (which expects relative milliseconds), care should be taken to convert + to a relative time and 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 + ppoll2 + instead of plain poll(), which understands timeouts 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 timeout 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_process3. + + + Note that these functions are only one of three supported ways to implement I/O event + handling for bus connections. Alternatively use + sd_bus_attach_event3 + to attach a bus connection to an + sd-event3 + event loop. Or use + sd_bus_wait3 + as a simple synchronous, blocking I/O waiting call. + + + + Return Value + + On success, sd_bus_get_fd() returns the file descriptor used for + communication. On failure, it returns a negative errno-style error code. + + On success, sd_bus_get_events() returns the I/O event mask to use for + I/O event watching. On failure, it returns a negative errno-style error code. + + On success, sd_bus_get_timeout() returns a non-negative integer. On + failure, it returns a negative errno-style error code. + + + 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. + + + + -ENOPKG + + The bus cannot be resolved. + + + + + + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_process3, + sd_bus_attach_event3, + sd_bus_wait3, + sd_bus_set_fd3, + poll3 + + + + -- cgit v1.2.3