1<?xml version='1.0'?>
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-or-later -->
5
6<refentry id="sd_bus_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
7
8  <refentryinfo>
9    <title>sd_bus_set_description</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>sd_bus_set_description</refentrytitle>
15    <manvolnum>3</manvolnum>
16  </refmeta>
17
18  <refnamediv>
19    <refname>sd_bus_set_description</refname>
20    <refname>sd_bus_get_description</refname>
21    <refname>sd_bus_set_anonymous</refname>
22    <refname>sd_bus_is_anonymous</refname>
23    <refname>sd_bus_set_trusted</refname>
24    <refname>sd_bus_is_trusted</refname>
25    <refname>sd_bus_set_allow_interactive_authorization</refname>
26    <refname>sd_bus_get_allow_interactive_authorization</refname>
27    <refname>sd_bus_get_scope</refname>
28    <refname>sd_bus_get_tid</refname>
29    <refname>sd_bus_get_unique_name</refname>
30
31    <refpurpose>Set or query properties of a bus object</refpurpose>
32  </refnamediv>
33
34  <refsynopsisdiv>
35    <funcsynopsis>
36      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
37
38      <funcprototype>
39        <funcdef>int <function>sd_bus_set_description</function></funcdef>
40        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
41        <paramdef>const char *<parameter>description</parameter></paramdef>
42      </funcprototype>
43
44      <funcprototype>
45        <funcdef>int <function>sd_bus_get_description</function></funcdef>
46        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
47        <paramdef>const char **<parameter>description</parameter></paramdef>
48      </funcprototype>
49
50      <funcprototype>
51        <funcdef>int <function>sd_bus_set_anonymous</function></funcdef>
52        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
53        <paramdef>int <parameter>b</parameter></paramdef>
54      </funcprototype>
55
56      <funcprototype>
57        <funcdef>int <function>sd_bus_is_anonymous</function></funcdef>
58        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
59      </funcprototype>
60
61      <funcprototype>
62        <funcdef>int <function>sd_bus_set_trusted</function></funcdef>
63        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
64        <paramdef>int <parameter>b</parameter></paramdef>
65      </funcprototype>
66
67      <funcprototype>
68        <funcdef>int <function>sd_bus_is_trusted</function></funcdef>
69        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
70      </funcprototype>
71
72      <funcprototype>
73        <funcdef>int <function>sd_bus_set_allow_interactive_authorization</function></funcdef>
74        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
75        <paramdef>int <parameter>b</parameter></paramdef>
76      </funcprototype>
77
78      <funcprototype>
79        <funcdef>int <function>sd_bus_get_allow_interactive_authorization</function></funcdef>
80        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
81      </funcprototype>
82
83      <funcprototype>
84        <funcdef>int <function>sd_bus_get_scope</function></funcdef>
85        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
86        <paramdef>const char **<parameter>scope</parameter></paramdef>
87      </funcprototype>
88
89      <funcprototype>
90        <funcdef>int <function>sd_bus_get_tid</function></funcdef>
91        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
92        <paramdef>pid_t *<parameter>tid</parameter></paramdef>
93      </funcprototype>
94
95      <funcprototype>
96        <funcdef>int <function>sd_bus_get_unique_name</function></funcdef>
97        <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
98        <paramdef>const char **<parameter>unique</parameter></paramdef>
99      </funcprototype>
100    </funcsynopsis>
101  </refsynopsisdiv>
102
103  <refsect1>
104    <title>Description</title>
105
106    <para><function>sd_bus_set_description()</function> sets the description string that is used in
107    logging to the specified string. The string is copied internally and freed when the bus object
108    is deallocated. The <parameter>description</parameter> argument may be
109    <constant>NULL</constant>, in which case the description is unset. This function must be called
110    before the bus is started.</para>
111
112    <para><function>sd_bus_get_description()</function> returns a description string in
113    <parameter>description</parameter>. This string may have been previously set with
114    <function>sd_bus_set_description()</function> or
115    <citerefentry><refentrytitle>sd_bus_open_with_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>
116    or similar. If not set this way, a default string like <literal>system</literal> or
117    <literal>user</literal> will be returned for the system or user buses, and
118    <constant>-ENXIO</constant> otherwise.</para>
119
120    <para><function>sd_bus_set_anonymous()</function> enables or disables "anonymous authentication",
121    i.e. lack of authentication, of the bus peer. This function must be called before the bus is
122    started. See the
123    <ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">
124    Authentication Mechanisms</ulink> section of the D-Bus specification for details.</para>
125
126    <para><function>sd_bus_is_anonymous()</function> returns true if the bus connection allows
127    anonymous authentication (in the sense described in previous paragraph).</para>
128
129    <para><function>sd_bus_set_trusted()</function> sets the "trusted" state on the
130    <parameter>bus</parameter> object. If true, all connections on the bus are trusted and access to
131    all privileged and unprivileged methods is granted. This function must be called before the bus
132    is started.</para>
133
134    <para><function>sd_bus_is_trusted()</function> returns true if the bus connection is trusted (in
135    the sense described in previous paragraph).</para>
136
137    <para><function>sd_bus_set_allow_interactive_authorization()</function> enables or disables
138    interactive authorization for method calls. If true, messages are marked with the
139    <constant>ALLOW_INTERACTIVE_AUTHORIZATION</constant> flag specified by the
140    <ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus</ulink>
141    specification, informing the receiving side that the caller is prepared to wait for interactive
142    authorization, which might take a considerable time to complete. If this flag is set, the user
143    may be queried for passwords or confirmation via
144    <ulink url="https://www.freedesktop.org/wiki/Software/polkit">polkit</ulink> or a similar
145    framework.</para>
146
147    <para><function>sd_bus_get_allow_interactive_authorization()</function> returns true if
148    interactive authorization is allowed and false if not.</para>
149
150    <para><function>sd_bus_get_scope()</function> stores the scope of the given bus object in
151    <parameter>scope</parameter>. The scope of the system bus is <literal>system</literal>. The
152    scope of a user session bus is <literal>user</literal>. If the given bus object is not the
153    system or a user session bus, <function>sd_bus_get_scope()</function> returns an error.</para>
154
155    <para><function>sd_bus_get_tid()</function> stores the kernel thread id of the thread associated
156    with the given bus object in <parameter>tid</parameter>. If <parameter>bus</parameter> is a
157    default bus object obtained by calling one of the functions of the
158    <citerefentry><refentrytitle>sd_bus_default</refentrytitle><manvolnum>3</manvolnum></citerefentry>
159    family of functions, it stores the thread id of the thread the bus object was created in.
160    Otherwise, if the bus object is attached to an event loop, it stores the thread id of the
161    thread the event loop object was created in. If <parameter>bus</parameter> is not a default bus
162    object and is not attached to an event loop, <function>sd_bus_get_tid()</function> returns an
163    error.</para>
164
165    <para><function>sd_bus_get_unique_name()</function> stores the unique name of the bus object on
166    the bus in <parameter>unique</parameter>. See
167    <ulink url="https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus">
168    The D-Bus specification</ulink> for more information on bus names. Note that the caller does not
169    own the string stored in <parameter>unique</parameter> and should not free it.</para>
170  </refsect1>
171
172  <refsect1>
173    <title>Return Value</title>
174
175    <para>On success, these functions return a non-negative integer. On failure, they return a
176    negative errno-style error code.</para>
177
178    <refsect2>
179      <title>Errors</title>
180
181      <para>Returned errors may indicate the following problems:</para>
182
183      <variablelist>
184        <varlistentry>
185          <term><constant>-EINVAL</constant></term>
186
187          <listitem><para>An argument is invalid.</para></listitem>
188        </varlistentry>
189
190        <varlistentry>
191          <term><constant>-ENOPKG</constant></term>
192
193          <listitem><para>The bus cannot be resolved.</para></listitem>
194        </varlistentry>
195
196        <varlistentry>
197          <term><constant>-EPERM</constant></term>
198
199          <listitem><para>The bus has already been started.</para></listitem>
200        </varlistentry>
201
202        <varlistentry>
203          <term><constant>-ECHILD</constant></term>
204
205          <listitem><para>The bus was created in a different process.</para></listitem>
206        </varlistentry>
207
208        <varlistentry>
209          <term><constant>-ENOMEM</constant></term>
210
211          <listitem><para>Memory allocation failed.</para></listitem>
212        </varlistentry>
213
214        <varlistentry>
215          <term><constant>-ENODATA</constant></term>
216
217          <listitem><para>The bus object passed to <function>sd_bus_get_scope()</function> was not a
218          system or user session bus.</para></listitem>
219        </varlistentry>
220
221        <varlistentry>
222          <term><constant>-ENXIO</constant></term>
223
224          <listitem><para>The bus object passed to <function>sd_bus_get_tid()</function> was not a
225          default bus object and is not attached to an event loop.</para>
226
227          <para>The bus object passed to <function>sd_bus_get_description()</function> did
228          not have a <parameter>description</parameter>.</para></listitem>
229        </varlistentry>
230      </variablelist>
231    </refsect2>
232  </refsect1>
233
234  <xi:include href="libsystemd-pkgconfig.xml" />
235
236  <refsect1>
237    <title>See Also</title>
238
239    <para>
240      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
241      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
242      <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
243      <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
244      <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
245      <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>
246    </para>
247  </refsect1>
248
249</refentry>
250