sd_bus_process(3) — Chainguard OS Manuals

SD_BUS_PROCESS(3)

sd_bus_process

SD_BUS_PROCESS(3)

.SH "NAME" sd_bus_process - Drive the connection

.SH "SYNOPSIS"

#include <systemd/sd-bus.h>

.HP 456u int sd_bus_process(sd_bus *bus, sd_bus_message **ret);

.SH "DESCRIPTION"

.PP 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).

.PP 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).

.PP 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.

.SH "RETURN VALUE"

.PP 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.

.SS "Errors"

.PP Returned errors may indicate the following problems:

.PP -EINVAL

An invalid bus object was passed.

.RE

.PP -ECHILD

The bus connection was allocated in a parent process and is being reused in a child process after fork().

.RE

.PP -ENOTCONN

The bus connection has been terminated already.

.RE

.PP -ECONNRESET

The bus connection has been terminated just now.

.RE

.PP -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().

.RE

.SH "NOTES"

.PP Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file.

.PP 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.

.PP 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.

.SH "HISTORY"

.PP sd_bus_process() was added in version 221.

systemd 262.2