# sd_bus_set_address

## NAME



           sd_bus_set_address, sd_bus_get_address, sd_bus_set_exec - Set or
           query the address of the bus connection
    


## SYNOPSIS



           **#include <systemd/sd-bus.h>**
    
           **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) 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**.
    
           •   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) 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). 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_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) 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) file.
    
           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.
    


* * *