---
name: "sd_bus_process"
section: "3"
platform: "linux"
package: "systemd-libs"
version: "262.1-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/sd_bus_process"
---

# sd\_bus\_process(3)

Drive the connection

## NAME

sd\_bus\_process - Drive the connection

## SYNOPSIS

```
#include <systemd/sd-bus.h>
```

**int sd\_bus\_process(sd\_bus \****bus***, sd\_bus\_message \*\****ret***);**

## DESCRIPTION

**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)](/sd_bus_wait/3.md) call, or hook up the bus connection object to an external or manual event loop using [**sd\_bus\_get\_fd**(3)](/sd_bus_get_fd/3.md).

**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)](/sd_bus_message_unref/3.md) 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)](/sd_bus_add_filter/3.md), object handlers registered via [**sd\_bus\_add\_object**(3)](/sd_bus_add_object/3.md), matches registered via [**sd\_bus\_add\_match**(3)](/sd_bus_add_match/3.md), 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)](/sd-event/3.md) event loop (with [**sd\_bus\_attach\_event**(3)](/sd_bus_attach_event/3.md)), 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.

### 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()**.

## NOTES

Functions described here are available as a shared library, which can be compiled against and linked to with the **libsystemd** [**pkg-config**(1)](/pkg-config/1.md) 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)](/getenv/3.md), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call [**setenv**(3)](/setenv/3.md) 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.

## HISTORY

**sd\_bus\_process()** was added in version 221.

## SEE ALSO

[**systemd**(1)](/systemd/1.md), [**sd-bus**(3)](/sd-bus/3.md), [**sd\_bus\_wait**(3)](/sd_bus_wait/3.md), [**sd\_bus\_get\_fd**(3)](/sd_bus_get_fd/3.md), [**sd\_bus\_message\_unref**(3)](/sd_bus_message_unref/3.md), [**sd-event**(3)](/sd-event/3.md), [**sd\_bus\_attach\_event**(3)](/sd_bus_attach_event/3.md)