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