sd_bus_process — Drive the connection
#include <systemd/sd-bus.h>
int sd_bus_process( | sd_bus *bus, |
sd_bus_message **ret); |
sd_bus_process() drives the connection between the client and the message bus.
That is, it handles connecting, authentication, and processing of messages. 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 poll for I/O events before calling into
sd_bus_process() again. For that either use the simple, blocking
sd_bus_wait(3) call, or
hook up the bus connection object to an external or manual event loop using
sd_bus_get_fd(3).
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_unref(3)
when the message is no longer needed. If ret is not NULL and
progress was made, but no message was processed, *ret is set to
NULL. Note that only messages not already handled by the various types of registered
message handlers (i.e. by filters registered via
sd_bus_add_filter(3),
object handlers registered via
sd_bus_add_object(3),
matches registered via
sd_bus_add_match(3),
and related) will be returned through this parameter. Also note that if such a message handler returns a
zero return value (as opposed to some value > 0) an incoming message will not be considered handled,
and be passed to other suitable handlers (until one returns > > 0), or returned by
sd_bus_process() (in case none returns > 0).
If the bus object is connected to an
sd-event(3) event loop (with
sd_bus_attach_event(3)), it is not
necessary to call sd_bus_process() directly as it is invoked automatically when
necessary.
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.
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().
Functions described here are available as a shared
library, which can be compiled against and linked to with the
libsystemd pkg-config(1)
file.
All functions listed here are thread-agnostic and only a single thread may operate on a given object at any given time. Different threads may access the same object at different times. Multiple independent objects may be used from different threads in parallel.
The code described here uses
getenv(3),
which is declared to be not multi-thread-safe. This means that the code calling the functions described
here must not call
setenv(3)
from a parallel thread. It is recommended to only do calls to setenv()
from an early phase of the program when no other threads have been started.