]> git.ipfire.org Git - thirdparty/systemd.git/blame - man/sd_bus_set_server.xml
update TODO
[thirdparty/systemd.git] / man / sd_bus_set_server.xml
CommitLineData
c40bd284
DDM
1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
eea10b26 3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
db9ecf05 4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
c40bd284
DDM
5
6<refentry id="sd_bus_set_server"
7 xmlns:xi="http://www.w3.org/2001/XInclude">
8
9 <refentryinfo>
10 <title>sd_bus_set_server</title>
11 <productname>systemd</productname>
12 </refentryinfo>
13
14 <refmeta>
15 <refentrytitle>sd_bus_set_server</refentrytitle>
16 <manvolnum>3</manvolnum>
17 </refmeta>
18
19 <refnamediv>
20 <refname>sd_bus_set_server</refname>
842a362c 21 <refname>sd_bus_is_server</refname>
c40bd284 22 <refname>sd_bus_get_bus_id</refname>
842a362c
DDM
23 <refname>sd_bus_set_bus_client</refname>
24 <refname>sd_bus_is_bus_client</refname>
0eb5b641
DDM
25 <refname>sd_bus_set_monitor</refname>
26 <refname>sd_bus_is_monitor</refname>
c40bd284 27
0eb5b641 28 <refpurpose>Configure connection mode for a bus object</refpurpose>
c40bd284
DDM
29 </refnamediv>
30
31 <refsynopsisdiv>
32 <funcsynopsis>
33 <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
34
35 <funcprototype>
36 <funcdef>int <function>sd_bus_set_server</function></funcdef>
37 <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
38 <paramdef>int <parameter>b</parameter></paramdef>
39 <paramdef>sd_id128_t <parameter>id</parameter></paramdef>
40 </funcprototype>
41
842a362c
DDM
42 <funcprototype>
43 <funcdef>int <function>sd_bus_is_server</function></funcdef>
44 <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
45 </funcprototype>
46
c40bd284
DDM
47 <funcprototype>
48 <funcdef>int <function>sd_bus_get_bus_id</function></funcdef>
49 <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
50 <paramdef>sd_id128_t *<parameter>id</parameter></paramdef>
51 </funcprototype>
842a362c
DDM
52
53 <funcprototype>
54 <funcdef>int <function>sd_bus_set_bus_client</function></funcdef>
55 <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
56 <paramdef>int <parameter>b</parameter></paramdef>
57 </funcprototype>
58
59 <funcprototype>
60 <funcdef>int <function>sd_bus_is_bus_client</function></funcdef>
61 <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
62 </funcprototype>
0eb5b641
DDM
63
64 <funcprototype>
65 <funcdef>int <function>sd_bus_set_monitor</function></funcdef>
66 <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
67 <paramdef>int <parameter>b</parameter></paramdef>
68 </funcprototype>
69
70 <funcprototype>
71 <funcdef>int <function>sd_bus_is_monitor</function></funcdef>
72 <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
73 </funcprototype>
c40bd284
DDM
74 </funcsynopsis>
75 </refsynopsisdiv>
76
77 <refsect1>
78 <title>Description</title>
79
7fffaafa
DDM
80 <para><function>sd_bus_set_server()</function> configures the bus object as a server for direct D-Bus
81 connections. <parameter>b</parameter> enables/disables the server mode. If zero, the server mode is
82 disabled. Otherwise, the server mode is enabled. Configuring a bus object as a server is required to
83 allow establishing direct connections between two peers without going via the D-Bus daemon.
84 <parameter>id</parameter> must contain a 128-bit integer id for the server. If clients add a guid field
85 to their D-Bus address string, the server id must match this guid or the D-Bus authentication handshake
86 will fail. If no specific id is defined for the server,
c40bd284
DDM
87 <citerefentry><refentrytitle>sd_id128_randomize</refentrytitle><manvolnum>3</manvolnum></citerefentry>
88 can be used to generate a random id instead.</para>
89
7fffaafa
DDM
90 <para><function>sd_bus_is_server()</function> returns whether the server mode is enabled for the given
91 bus object.</para>
842a362c 92
c40bd284 93 <para><function>sd_bus_get_bus_id()</function> stores the D-Bus server id configured using
7fffaafa
DDM
94 <function>sd_bus_set_server()</function> (for server bus objects) or received during D-Bus authentication
95 (for client bus objects) in <parameter>id</parameter>.</para>
96
97 <para><function>sd_bus_set_bus_client()</function> configures the bus object as a D-Bus daemon client.
98 <parameter>b</parameter> enables/disables the client mode. If zero, the client mode is disabled and the
99 bus object should connect directly to a D-Bus server. Otherwise, the client mode is enabled and the bus
100 object should connect to a D-Bus daemon. When connecting to an existing bus using any of the functions in
101 the <citerefentry><refentrytitle>sd_bus_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>
842a362c 102 family of functions or any of the functions in the
7fffaafa
DDM
103 <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry> family
104 of functions, the bus object is automatically configured as a bus client. However, when connecting to a
105 D-Bus daemon by calling
842a362c
DDM
106 <citerefentry><refentrytitle>sd_bus_set_address</refentrytitle><manvolnum>3</manvolnum></citerefentry>
107 followed by
7fffaafa
DDM
108 <citerefentry><refentrytitle>sd_bus_start</refentrytitle><manvolnum>3</manvolnum></citerefentry>, the bus
109 object should be manually configured as a bus client using <function>sd_bus_set_bus_client()</function>.
110 By default, a bus object is not configured as a D-Bus daemon client.</para>
842a362c 111
7fffaafa
DDM
112 <para><function>sd_bus_is_bus_client()</function> returns whether the client mode is enabled/disabled for
113 the given bus object.</para>
0eb5b641
DDM
114
115 <para><function>sd_bus_set_monitor()</function> configures the bus object as a D-Bus monitor object.
116 <parameter>b</parameter> enables/disables the monitor mode. If zero, the monitor mode is disabled. If
117 non-zero, the monitor mode is enabled. When the monitor mode is enabled, no messages may be sent via the
118 bus object and it may not expose any objects on the bus. To start monitoring messages, call the
119 <function>org.freedesktop.DBus.Monitoring.BecomeMonitor</function> method of the D-Bus daemon and pass
120 a list of matches indicating which messages to intercept. See
121 <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-become-monitor">
122 The D-Bus specification</ulink> for more information.</para>
123
124 <para><function>sd_bus_is_monitor()</function> returns whether the monitor mode is enabled/disabled for
125 the given bus object.</para>
126
c40bd284
DDM
127 </refsect1>
128
129 <refsect1>
130 <title>Return Value</title>
131
842a362c 132 <para>On success, <function>sd_bus_set_server()</function>,
0eb5b641
DDM
133 <function>sd_bus_get_bus_id()</function>, <function>sd_bus_set_bus_client()</function> and
134 <function>sd_bus_set_monitor()</function> return a non-negative integer. On failure, they return a
135 negative errno-style error code.</para>
842a362c 136
0eb5b641
DDM
137 <para><function>sd_bus_is_server()</function>, <function>sd_bus_is_bus_client()</function> and
138 <function>sd_bus_is_monitor()</function> return a positive integer when the server or client mode is
139 enabled, respectively. Otherwise, they return zero.</para>
c40bd284
DDM
140
141 <refsect2>
142 <title>Errors</title>
143
144 <para>Returned errors may indicate the following problems:</para>
145
146 <variablelist>
147 <varlistentry>
148 <term><constant>-ECHILD</constant></term>
149
ec07c3c8
AK
150 <listitem><para>The bus connection has been created in a different process, library or module instance.</para>
151
152 <xi:include href="version-info.xml" xpointer="v246"/></listitem>
c40bd284
DDM
153 </varlistentry>
154
155 <varlistentry>
156 <term><constant>-EPERM</constant></term>
157
ec07c3c8
AK
158 <listitem><para>The bus connection has already been started.</para>
159
160 <xi:include href="version-info.xml" xpointer="v246"/></listitem>
c40bd284
DDM
161 </varlistentry>
162
163 <varlistentry>
164 <term><constant>-ENOPKG</constant></term>
165
ec07c3c8
AK
166 <listitem><para>The bus cannot be resolved.</para>
167
168 <xi:include href="version-info.xml" xpointer="v246"/></listitem>
c40bd284
DDM
169 </varlistentry>
170
171 <varlistentry>
172 <term><constant>-EINVAL</constant></term>
173
174 <listitem><para>A required parameter was <constant>NULL</constant> or
175 <parameter>b</parameter> was zero and <parameter>id</parameter> did not equal
ec07c3c8
AK
176 <constant>SD_ID128_NULL</constant>.</para>
177
178 <xi:include href="version-info.xml" xpointer="v246"/></listitem>
c40bd284
DDM
179 </varlistentry>
180
181 <varlistentry>
182 <term><constant>-ENOTCONN</constant></term>
183
ec07c3c8
AK
184 <listitem><para>The bus is not connected.</para>
185
186 <xi:include href="version-info.xml" xpointer="v246"/></listitem>
c40bd284
DDM
187 </varlistentry>
188 </variablelist>
189 </refsect2>
190 </refsect1>
191
192 <xi:include href="libsystemd-pkgconfig.xml" />
193
69106f47
AK
194 <refsect1>
195 <title>History</title>
00f95506
AK
196 <para><function>sd_bus_set_server()</function>,
197 <function>sd_bus_is_server()</function>,
198 <function>sd_bus_get_bus_id()</function>,
199 <function>sd_bus_set_bus_client()</function>,
200 <function>sd_bus_is_bus_client()</function>,
201 <function>sd_bus_set_monitor()</function>, and
202 <function>sd_bus_is_monitor()</function> were added in version 246.</para>
69106f47
AK
203 </refsect1>
204
c40bd284
DDM
205 <refsect1>
206 <title>See Also</title>
207
13a69c12
DT
208 <para><simplelist type="inline">
209 <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
210 <member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
211 </simplelist></para>
c40bd284
DDM
212 </refsect1>
213
214</refentry>