diff --git a/man/rules/meson.build b/man/rules/meson.build
index b091859829..0c990a0c5d 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -194,7 +194,7 @@ manpages = [
'3',
['SD_BUS_ERROR_END', 'SD_BUS_ERROR_MAP', 'sd_bus_error_map'],
''],
- ['sd_bus_get_fd', '3', [], ''],
+ ['sd_bus_get_fd', '3', ['sd_bus_get_events', 'sd_bus_get_timeout'], ''],
['sd_bus_get_n_queued_read', '3', ['sd_bus_get_n_queued_write'], ''],
['sd_bus_is_open', '3', ['sd_bus_is_ready'], ''],
['sd_bus_message_append', '3', ['sd_bus_message_appendv'], ''],
@@ -347,6 +347,7 @@ manpages = [
'sd_bus_track_unref',
'sd_bus_track_unrefp'],
''],
+ ['sd_bus_wait', '3', [], ''],
['sd_event_add_child',
'3',
['sd_event_child_handler_t', 'sd_event_source_get_child_pid'],
diff --git a/man/sd_bus_attach_event.xml b/man/sd_bus_attach_event.xml
index 45f034910f..a2f7297f21 100644
--- a/man/sd_bus_attach_event.xml
+++ b/man/sd_bus_attach_event.xml
@@ -71,6 +71,13 @@
The sd_bus_get_event() returns the event loop object the specified bus object is
currently attached to, or NULL if it is currently not attached to any.
+
+ Note that sd_bus_attach_event() is only one of three supported ways to implement I/O
+ event handling for bus connections. Alternatively use
+ sd_bus_get_fd3 for hooking up a
+ bus connection object with external or manual event loops. Or use
+ sd_bus_wait3 as a simple
+ synchronous, blocking I/O waiting call.
@@ -107,7 +114,8 @@
sd-event3,
sd_event_source_set_priority3,
sd_bus_set_close_on_exit3,
- sd_bus_wait3
+ sd_bus_wait3,
+ sd_bus_get_fd3
diff --git a/man/sd_bus_get_fd.xml b/man/sd_bus_get_fd.xml
index 6f709df4c0..2a81bddaa0 100644
--- a/man/sd_bus_get_fd.xml
+++ b/man/sd_bus_get_fd.xml
@@ -8,7 +8,7 @@
Copyright © 2016 Julian Orth
-->
-
+
sd_bus_get_fd
@@ -22,8 +22,10 @@
sd_bus_get_fd
+ sd_bus_get_events
+ sd_bus_get_timeout
- Get the file descriptor connected to the message bus
+ Get the file descriptor, I/O events and time-out to wait for from a message bus object
@@ -34,39 +36,113 @@
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 with the message bus. This descriptor can be used with
- select3,
- poll3,
- or similar functions to wait for incoming messages.
-
+ 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_fd3 function, then
+ the input_fd file descriptor used in that call is returned.
-
- If the bus was created with the
- sd_bus_set_fd3
- function, then the input_fd 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 ppoll3
+ 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_process3.
+
+ 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_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
-
- Returns the file descriptor used for incoming messages from the message
- bus.
-
+ 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
@@ -74,6 +150,10 @@
systemd1,
sd-bus3,
sd_bus_set_fd3,
+ sd_bus_process3,
+ sd_bus_attach_event3,
+ sd_bus_wait3,
+ poll3
diff --git a/man/sd_bus_process.xml b/man/sd_bus_process.xml
index b78192990c..66f22c29a6 100644
--- a/man/sd_bus_process.xml
+++ b/man/sd_bus_process.xml
@@ -8,7 +8,7 @@
Copyright © 2016 Julian Orth
-->
-
+
sd_bus_process
@@ -33,7 +33,7 @@
int sd_bus_process
sd_bus *bus
- sd_bus_message **r
+ sd_bus_message **ret
@@ -41,49 +41,92 @@
Description
-
- sd_bus_process() drives the connection between the
- message bus and the client. That is, it handles connecting,
- authentication, and message processing. It should be called in a loop
- until no further progress can be made or an error occurs.
+ sd_bus_process() drives the connection between the client and the message bus. That is,
+ it handles connecting, authentication, and message processing. When invoked pending I/O work is executed, and
+ queued incoming messages are dispatched to registered callbacks. Each time it is invoked a single operation is
+ executed. It returns zero when no operations were pending and positive if a message was processed. When zero is
+ returned the caller should synchronously poll for I/O events before calling into
+ sd_bus_process() again. For that either user the simple, synchronous
+ sd_bus_wait3 call, or hook up
+ the bus connection object to an external or manual event loop using
+ sd_bus_get_fd3.
-
- Once no further progress can be made,
- sd_bus_wait3
- should be called. Alternatively the user can wait for incoming data on
- the file descriptor returned by
- sd_bus_get_fd3.
-
+ sd_bus_process() processes at most one incoming message per call. If the parameter
+ ret is not NULL and the call processed a message,
+ *ret is set to this message. The caller owns a reference to this message and should call
+ sd_bus_message_unref3 when the
+ message is no longer needed. If ret is not NULL, progress was made, but no message was
+ processed, *ret is set to NULL.
-
- sd_bus_process processes at most one incoming
- message per call. If the parameter r is not NULL
- and the call processed a message, *r
is set to this message.
- The caller owns a reference to this message and should call
- sd_bus_message_unref3
- when the message is no longer needed. If r is not
- NULL, progress was made, but no message was processed, *r
is
- set to NULL.
-
+ If a the bus object is connected to an
+ sd-event3 event loop (with
+ sd_bus_attach_event3), it is not
+ necessary to call sd_bus_process() directly as it is invoked automatically when
+ necessary.
Return Value
-
- If progress was made, a positive integer is returned. If no progress was
- made, 0 is returned. If an error occurs, a negative errno-style error code
- is returned.
-
+ If progress was made, a positive integer is returned. If no progress was made, 0 is returned. If an error
+ occurs, a negative errno-style error code is returned.
+
+ 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 already.
+
+
+
+ -ECONNRESET
+
+ The bus connection has been terminated just now.
+
+
+
+ -EBUSY
+
+ This function is already being called, i.e. sd_bus_process() has been
+ called from a callback function that itself was called by
+ sd_bus_process().
+
+
+
+
+
+
See Also
systemd1,
sd-bus3,
+ sd_bus_wait3,
+ sd_bus_get_fd3,
+ sd_bus_message_unref3,
+ sd-event3,
+ sd_bus_attach_event3
diff --git a/man/sd_bus_wait.xml b/man/sd_bus_wait.xml
new file mode 100644
index 0000000000..e866eeb20b
--- /dev/null
+++ b/man/sd_bus_wait.xml
@@ -0,0 +1,113 @@
+
+
+
+
+
+
+
+
+ sd_bus_wait
+ systemd
+
+
+
+ sd_bus_wait
+ 3
+
+
+
+ sd_bus_wait
+
+ Wait for I/O on a bus connection
+
+
+
+
+ #include <systemd/sd-bus.h>
+
+
+ int sd_bus_wait
+ sd_bus *bus
+ uint64_t timeout_usec
+
+
+
+
+
+ Description
+
+ sd_bus_wait() synchronously waits for I/O on the specified bus connection object. This
+ function is supposed to be called whenever
+ sd_bus_process3 returns zero,
+ indicating that no work is pending on the connection. Internally, this call invokes ppoll3, to wait for I/O on
+ the bus connection. If the timeout_sec parameter is specified, the call will block at most
+ for the specified amount of time in µs. Pass UINT64_MAX to permit it to sleep
+ indefinitely.
+
+ After each invocation of sd_bus_wait() the sd_bus_process() call
+ should be invoked in order to process any now pending I/O work.
+
+ Note that sd_bus_wait() is suitable only for simple programs as it does not permit
+ waiting for other I/O events. For more complex programs either connect the bus connection object to an external
+ event loop using sd_bus_get_fd3
+ or to an sd-event3 event loop
+ using
+ sd_bus_attach_event3.
+
+
+
+ Return Value
+
+ If any I/O was seen, a positive value is returned, zero otherwise. If an error occurs, a negative
+ errno-style error code is returned.
+
+
+
+ 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 already.
+
+
+
+
+
+
+
+ See Also
+
+
+ systemd1,
+ sd-bus3,
+ sd_bus_process3,
+ sd_bus_get_fd3,
+ sd-event3,
+ sd_bus_attach_event3
+
+
+
+