sd_bus_set_address(3)

1SD_BUS_SET_ADDRESS(3)         sd_bus_set_address         SD_BUS_SET_ADDRESS(3)
2
3
4

NAME

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

SYNOPSIS

10       #include <systemd/sd-bus.h>
11
12       int sd_bus_set_address(sd_bus *bus, const char *address);
13
14       int sd_bus_get_address(sd_bus *bus, const char **address);
15
16       int sd_bus_set_exec(sd_bus *bus, const char *path, char *const *argv);
17

DESCRIPTION

19       sd_bus_set_address() configures a list of addresses of bus brokers to
20       try to connect to from a subsequent sd_bus_start(3) call. The argument
21       is a ";"-separated list of addresses to try. Each item must be one of
22       the following:
23
24       •   A unix socket address specified as "unix:guid=guid,path=path" or
25           "unix:guid=guid,abstract=path". Exactly one of the path= and
26           abstract= keys must be present, while guid= is optional.
27
28       •   A TCP socket address specified as
29           "tcp:[guid=guid,][host=host][,port=port][,family=family]". One or
30           both of the host= and port= keys must be present, while the rest is
31           optional.  family may be either ipv4 or ipv6.
32
33       •   An executable to spawn specified as
34           "unixexec:guid=guid,path=path,argv1=argument,argv2=argument,...".
35           The path= key must be present, while guid= is optional.
36
37       •   A machine (container) to connect to specified as
38           "x-machine-unix:guid=guid,machine=machine,pid=pid". Exactly one of
39           the machine= and pid= keys must be present, while guid= is
40           optional.  machine is the name of a local container. See
41           machinectl(1) for more information about the "machine" concept.
42           "machine=.host" may be used to specify the host machine. A
43           connection to the standard system bus socket inside of the
44           specified machine will be created.
45
46       In all cases, parameter guid is an identifier of the remote peer, in
47       the syntax accepted by sd_id128_from_string(3). If specified, the
48       identifier returned by the peer after the connection is established
49       will be checked and the connection will be rejected in case of a
50       mismatch.
51
52       Note that the addresses passed to sd_bus_set_address() may not be
53       verified immediately. If they are invalid, an error may be returned
54       e.g. from a subsequent call to sd_bus_start(3).
55
56       sd_bus_get_address() returns any previously set addresses. In addition
57       to being explicitly set by sd_bus_set_address(), the address will also
58       be set automatically by sd_bus_open(3) and similar calls, based on
59       environment variables or built-in defaults.
60
61       sd_bus_set_exec() is a shorthand function for setting a "unixexec"
62       address that spawns the given executable with the given arguments. If
63       argv is NULL, the given executable is spawned without any extra
64       arguments.
65

RETURN VALUE

67       On success, these functions return a non-negative integer. On failure,
68       they return a negative errno-style error code.
69
70   Errors
71       Returned errors may indicate the following problems:
72
73       -EINVAL
74           The input parameters bus or address are NULL.
75
76       -ENOPKG
77           The bus object bus could not be resolved.
78
79       -EPERM
80           The input parameter bus is in a wrong state (sd_bus_set_address()
81           may only be called once on a newly-created bus object).
82
83       -ECHILD
84           The bus object bus was created in a different process.
85
86       -ENODATA
87           The bus object bus has no address configured.
88

NOTES

90       These APIs are implemented as a shared library, which can be compiled
91       and linked to with the libsystemd pkg-config(1) file.
92

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

NOTES

SEE ALSO