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>
23 <refpurpose>Set or query the address of the bus connection
</refpurpose>
28 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
31 <funcdef>int
<function>sd_bus_set_address
</function></funcdef>
32 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
33 <paramdef>const char*
<parameter>address
</parameter></paramdef>
37 <funcdef>int
<function>sd_bus_get_address
</function></funcdef>
38 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
39 <paramdef>const char**
<parameter>address
</parameter></paramdef>
46 <title>Description
</title>
48 <para><function>sd_bus_set_address()
</function> configures a list of addresses of bus brokers to try to
49 connect to from a subsequent
50 <citerefentry><refentrytitle>sd_bus_start
</refentrytitle><manvolnum>3</manvolnum></citerefentry> call.
51 The argument is a
<literal>;
</literal>-separated list of addresses to try. Each item must be one of the
57 <para>A unix socket address specified as
58 <literal>unix:guid=
<replaceable>guid
</replaceable>,path=
<replaceable>path
</replaceable></literal> or
59 <literal>unix:guid=
<replaceable>guid
</replaceable>,abstract=
<replaceable>path
</replaceable></literal>.
60 Exactly one of the
<varname>path=
</varname> and
<varname>abstract=
</varname> keys must be present,
61 while
<varname>guid=
</varname> is optional.
</para>
65 <para>A TCP socket address specified as
66 <literal>tcp:[guid=
<replaceable>guid
</replaceable>,][host=
<replaceable>host
</replaceable>][,port=
<replaceable>port
</replaceable>][,family=
<replaceable>family
</replaceable>]
</literal>.
67 One or both of the
<varname>host=
</varname> and
<varname>port=
</varname> keys must be present, while
68 the rest is optional.
<replaceable>family
</replaceable> may be either
<option>ipv4
</option> or
69 <option>ipv6
</option>.
</para>
73 <para>An executable to spawn specified as
74 <literal>unixexec:guid=
<replaceable>guid
</replaceable>,path=
<replaceable>path
</replaceable>,argv1=
<replaceable>argument
</replaceable>,argv2=
<replaceable>argument
</replaceable>,...
</literal>.
75 The
<varname>path=
</varname> key must be present, while
<varname>guid=
</varname> is optional.
</para>
79 <para>A machine (container) to connect to specified as
80 <literal>x-machine-unix:guid=
<replaceable>guid
</replaceable>,machine=
<replaceable>machine
</replaceable>,pid=
<replaceable>pid
</replaceable></literal>.
81 Exactly one of the
<varname>machine=
</varname> and
<varname>pid=
</varname> keys must be present,
82 while
<varname>guid=
</varname> is optional.
<parameter>machine
</parameter> is the name of a local
84 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
85 more information about the
"machine" concept.
<literal>machine=.host
</literal> may be used to specify
86 the host machine. A connection to the standard system bus socket inside of the specified machine will
91 <para>In all cases, parameter
<parameter>guid
</parameter> is an identifier of the remote peer, in the
93 <citerefentry><refentrytitle>sd_id128_from_string
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
94 If specified, the identifier returned by the peer after the connection is established will be checked and
95 the connection will be rejected in case of a mismatch.
</para>
97 <para>Note that the addresses passed to
<function>sd_bus_set_address()
</function> may not be verified
98 immediately. If they are invalid, an error may be returned e.g. from a subsequent call to
99 <citerefentry><refentrytitle>sd_bus_start
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
102 <para><function>sd_bus_get_address()
</function> returns any previously set addresses. In addition to
103 being explicitly set by
<function>sd_bus_set_address()
</function>, the address will also be set
105 <citerefentry><refentrytitle>sd_bus_open
</refentrytitle><manvolnum>3</manvolnum></citerefentry> and
106 similar calls, based on environment variables or built-in defaults.
</para>
110 <title>Return Value
</title>
112 <para>On success, these functions return a non-negative integer. On failure, they return a negative
113 errno-style error code.
</para>
116 <title>Errors
</title>
118 <para>Returned errors may indicate the following problems:
</para>
122 <term><constant>-EINVAL
</constant></term>
124 <listitem><para>The input parameters
<parameter>bus
</parameter> or
<parameter>address
</parameter> are
<constant>NULL
</constant>.
129 <term><constant>-ENOPKG
</constant></term>
131 <listitem><para>The bus object
<parameter>bus
</parameter> could not be resolved.
</para>
136 <term><constant>-EPERM
</constant></term>
138 <listitem><para>The input parameter
<parameter>bus
</parameter> is in a wrong state
139 (
<function>sd_bus_set_address()
</function> may only be called once on a newly-created bus object).
</para>
144 <term><constant>-ECHILD
</constant></term>
146 <listitem><para>The bus object
<parameter>bus
</parameter> was created in a different
152 <term><constant>-ENODATA
</constant></term>
154 <listitem><para>The bus object
<parameter>bus
</parameter> has no address configured.
</para>
161 <xi:include href=
"libsystemd-pkgconfig.xml" />
164 <title>See Also
</title>
167 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
168 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
169 <citerefentry><refentrytitle>sd_bus_new
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
170 <citerefentry><refentrytitle>sd_bus_start
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
171 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
172 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>