--- name: "sd_bus_set_address" 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_set_address" --- # sd\_bus\_set\_address(3) Set or query the address of the bus connection ## NAME sd\_bus\_set\_address, sd\_bus\_get\_address, sd\_bus\_set\_exec - Set or query the address of the bus connection ## SYNOPSIS ``` #include ``` **int sd\_bus\_set\_address(sd\_bus \****bus***, const char \****address***);** **int sd\_bus\_get\_address(sd\_bus \****bus***, const char \*\****address***);** **int sd\_bus\_set\_exec(sd\_bus \****bus***, const char \****path***, char \*const \****argv***);** ## DESCRIPTION **sd\_bus\_set\_address()** configures a list of addresses of bus brokers to try to connect to from a subsequent [**sd\_bus\_start**(3)](/sd_bus_start/3.md) call. The argument is a ";"-separated list of addresses to try. Each item must be one of the following: • A unix socket address specified as "unix:guid=*guid*,path=*path*" or "unix:guid=*guid*,abstract=*path*". Exactly one of the *path=* and *abstract=* keys must be present, while *guid=* is optional. • A TCP socket address specified as "tcp:\[guid=*guid*,\]\[host=*host*\]\[,port=*port*\]\[,family=*family*\]". One or both of the *host=* and *port=* keys must be present, while the rest is optional. *family* may be either **ipv4** or **ipv6**. Note: *connections over TCP are made without encryption*. Thus, this mode should only be used in specific situations where integrity and confidentiality of the connection is not necessary or is ensured through some other means. For local connections, "unix:" connections should be used instead. • An executable to spawn specified as "unixexec:guid=*guid*,path=*path*,argv1=*argument*,argv2=*argument*,...". The *path=* key must be present, while *guid=* is optional. • A machine (container) to connect to specified as "x-machine-unix:guid=*guid*,machine=*machine*,pid=*pid*". Exactly one of the *machine=* and *pid=* keys must be present, while *guid=* is optional. *machine* is the name of a local container. See [**machinectl**(1)](/machinectl/1.md) for more information about the "machine" concept. "machine=.host" may be used to specify the host machine. A connection to the standard system bus socket inside of the specified machine will be created. In all cases, parameter *guid* is an identifier of the remote peer, in the syntax accepted by [**sd\_id128\_from\_string**(3)](/sd_id128_from_string/3.md). If specified, the identifier returned by the peer after the connection is established will be checked and the connection will be rejected in case of a mismatch. Note that the addresses passed to **sd\_bus\_set\_address()** might not be verified immediately. If they are invalid, an error may be returned e.g. from a subsequent call to [**sd\_bus\_start**(3)](/sd_bus_start/3.md). **sd\_bus\_get\_address()** returns any previously set addresses. In addition to being explicitly set by **sd\_bus\_set\_address()**, the address will also be set automatically by [**sd\_bus\_open**(3)](/sd_bus_open/3.md) and similar calls, based on environment variables or built-in defaults. **sd\_bus\_set\_exec()** is a shorthand function for setting a "unixexec" address that spawns the given executable with the given arguments. If *argv* is **NULL**, the given executable is spawned without any extra arguments. ## RETURN VALUE On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code. ### Errors Returned errors may indicate the following problems: **-EINVAL** The input parameters *bus* or *address* are **NULL**. Added in version 246. **-ENOPKG** The bus object *bus* could not be resolved. Added in version 246. **-EPERM** The input parameter *bus* is in a wrong state (**sd\_bus\_set\_address()** may only be called once on a newly-created bus object). Added in version 246. **-ECHILD** The bus object *bus* was created in a different process. Added in version 246. **-ENODATA** The bus object *bus* has no address configured. Added in version 246. ## 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\_set\_address()**, **sd\_bus\_get\_address()**, and **sd\_bus\_set\_exec()** were added in version 246. ## SEE ALSO [**systemd**(1)](/systemd/1.md), [**sd-bus**(3)](/sd-bus/3.md), [**sd\_bus\_new**(3)](/sd_bus_new/3.md), [**sd\_bus\_start**(3)](/sd_bus_start/3.md), [**systemd-machined.service**(8)](/systemd-machined.service/8.md), [**machinectl**(1)](/machinectl/1.md)