sd_bus_process(3)

1SD_BUS_PROCESS(3)               sd_bus_process               SD_BUS_PROCESS(3)
2
3
4

NAME

6       sd_bus_process - Drive the connection
7

SYNOPSIS

9       #include <systemd/sd-bus.h>
10
11       int sd_bus_process(sd_bus *bus, sd_bus_message **ret);
12

DESCRIPTION

14       sd_bus_process() drives the connection between the client and the
15       message bus. That is, it handles connecting, authentication, and
16       message processing. When invoked pending I/O work is executed, and
17       queued incoming messages are dispatched to registered callbacks. Each
18       time it is invoked a single operation is executed. It returns zero when
19       no operations were pending and positive if a message was processed.
20       When zero is returned the caller should synchronously poll for I/O
21       events before calling into sd_bus_process() again. For that either use
22       the simple, synchronous sd_bus_wait(3) call, or hook up the bus
23       connection object to an external or manual event loop using
24       sd_bus_get_fd(3).
25
26       sd_bus_process() processes at most one incoming message per call. If
27       the parameter ret is not NULL and the call processed a message, *ret is
28       set to this message. The caller owns a reference to this message and
29       should call sd_bus_message_unref(3) when the message is no longer
30       needed. If ret is not NULL, progress was made, but no message was
31       processed, *ret is set to NULL.
32
33       If the bus object is connected to an sd-event(3) event loop (with
34       sd_bus_attach_event(3)), it is not necessary to call sd_bus_process()
35       directly as it is invoked automatically when necessary.
36

RETURN VALUE

38       If progress was made, a positive integer is returned. If no progress
39       was made, 0 is returned. If an error occurs, a negative errno-style
40       error code is returned.
41
42   Errors
43       Returned errors may indicate the following problems:
44
45       -EINVAL
46           An invalid bus object was passed.
47
48       -ECHILD
49           The bus connection was allocated in a parent process and is being
50           reused in a child process after fork().
51
52       -ENOTCONN
53           The bus connection has been terminated already.
54
55       -ECONNRESET
56           The bus connection has been terminated just now.
57
58       -EBUSY
59           This function is already being called, i.e.  sd_bus_process() has
60           been called from a callback function that itself was called by
61           sd_bus_process().
62

NOTES

64       Functions described here are available as a shared library, which can
65       be compiled against and linked to with the libsystemd pkg-config(1)
66       file.
67
68       The code described here uses getenv(3), which is declared to be not
69       multi-thread-safe. This means that the code calling the functions
70       described here must not call setenv(3) from a parallel thread. It is
71       recommended to only do calls to setenv() from an early phase of the
72       program when no other threads have been started.
73

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO