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