2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"sd_bus_set_address"
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>sd_bus_set_address
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>sd_bus_set_address
</refentrytitle>
16 <manvolnum>3</manvolnum>
20 <refname>sd_bus_set_address
</refname>
21 <refname>sd_bus_get_address
</refname>
22 <refname>sd_bus_set_exec
</refname>
24 <refpurpose>Set or query the address of the bus connection
</refpurpose>
29 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
32 <funcdef>int
<function>sd_bus_set_address
</function></funcdef>
33 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
34 <paramdef>const char *
<parameter>address
</parameter></paramdef>
38 <funcdef>int
<function>sd_bus_get_address
</function></funcdef>
39 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
40 <paramdef>const char **
<parameter>address
</parameter></paramdef>
44 <funcdef>int
<function>sd_bus_set_exec
</function></funcdef>
45 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
46 <paramdef>const char *
<parameter>path
</parameter></paramdef>
47 <paramdef>char *const *
<parameter>argv
</parameter></paramdef>
53 <title>Description
</title>
55 <para><function>sd_bus_set_address()
</function> configures a list of addresses of bus brokers to try to
56 connect to from a subsequent
57 <citerefentry><refentrytitle>sd_bus_start
</refentrytitle><manvolnum>3</manvolnum></citerefentry> call.
58 The argument is a
<literal>;
</literal>-separated list of addresses to try. Each item must be one of the
64 <para>A unix socket address specified as
65 <literal>unix:guid=
<replaceable>guid
</replaceable>,path=
<replaceable>path
</replaceable></literal> or
66 <literal>unix:guid=
<replaceable>guid
</replaceable>,abstract=
<replaceable>path
</replaceable></literal>.
67 Exactly one of the
<varname>path=
</varname> and
<varname>abstract=
</varname> keys must be present,
68 while
<varname>guid=
</varname> is optional.
</para>
72 <para>A TCP socket address specified as
73 <literal>tcp:[guid=
<replaceable>guid
</replaceable>,][host=
<replaceable>host
</replaceable>][,port=
<replaceable>port
</replaceable>][,family=
<replaceable>family
</replaceable>]
</literal>.
74 One or both of the
<varname>host=
</varname> and
<varname>port=
</varname> keys must be present, while
75 the rest is optional.
<replaceable>family
</replaceable> may be either
<option>ipv4
</option> or
76 <option>ipv6
</option>.
</para>
80 <para>An executable to spawn specified as
81 <literal>unixexec:guid=
<replaceable>guid
</replaceable>,path=
<replaceable>path
</replaceable>,argv1=
<replaceable>argument
</replaceable>,argv2=
<replaceable>argument
</replaceable>,...
</literal>.
82 The
<varname>path=
</varname> key must be present, while
<varname>guid=
</varname> is optional.
</para>
86 <para>A machine (container) to connect to specified as
87 <literal>x-machine-unix:guid=
<replaceable>guid
</replaceable>,machine=
<replaceable>machine
</replaceable>,pid=
<replaceable>pid
</replaceable></literal>.
88 Exactly one of the
<varname>machine=
</varname> and
<varname>pid=
</varname> keys must be present,
89 while
<varname>guid=
</varname> is optional.
<parameter>machine
</parameter> is the name of a local
91 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
92 more information about the
"machine" concept.
<literal>machine=.host
</literal> may be used to specify
93 the host machine. A connection to the standard system bus socket inside of the specified machine will
98 <para>In all cases, parameter
<parameter>guid
</parameter> is an identifier of the remote peer, in the
100 <citerefentry><refentrytitle>sd_id128_from_string
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
101 If specified, the identifier returned by the peer after the connection is established will be checked and
102 the connection will be rejected in case of a mismatch.
</para>
104 <para>Note that the addresses passed to
<function>sd_bus_set_address()
</function> may not be verified
105 immediately. If they are invalid, an error may be returned e.g. from a subsequent call to
106 <citerefentry><refentrytitle>sd_bus_start
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
109 <para><function>sd_bus_get_address()
</function> returns any previously set addresses. In addition to
110 being explicitly set by
<function>sd_bus_set_address()
</function>, the address will also be set
112 <citerefentry><refentrytitle>sd_bus_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
113 similar calls, based on environment variables or built-in defaults.
</para>
115 <para><function>sd_bus_set_exec
</function> is a shorthand function for setting a
116 <literal>unixexec
</literal> address that spawns the given executable with the given arguments.
117 If
<parameter>argv
</parameter> is
<constant>NULL
</constant>, the given executable is spawned
118 without any extra arguments.
</para>
122 <title>Return Value
</title>
124 <para>On success, these functions return a non-negative integer. On failure, they return a negative
125 errno-style error code.
</para>
128 <title>Errors
</title>
130 <para>Returned errors may indicate the following problems:
</para>
134 <term><constant>-EINVAL
</constant></term>
136 <listitem><para>The input parameters
<parameter>bus
</parameter> or
<parameter>address
</parameter> are
<constant>NULL
</constant>.
141 <term><constant>-ENOPKG
</constant></term>
143 <listitem><para>The bus object
<parameter>bus
</parameter> could not be resolved.
</para>
148 <term><constant>-EPERM
</constant></term>
150 <listitem><para>The input parameter
<parameter>bus
</parameter> is in a wrong state
151 (
<function>sd_bus_set_address()
</function> may only be called once on a newly-created bus object).
</para>
156 <term><constant>-ECHILD
</constant></term>
158 <listitem><para>The bus object
<parameter>bus
</parameter> was created in a different
164 <term><constant>-ENODATA
</constant></term>
166 <listitem><para>The bus object
<parameter>bus
</parameter> has no address configured.
</para>
173 <xi:include href=
"libsystemd-pkgconfig.xml" />
176 <title>See Also
</title>
179 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
180 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
181 <citerefentry><refentrytitle>sd_bus_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
182 <citerefentry><refentrytitle>sd_bus_start
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
183 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
184 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>