]>
Commit | Line | Data |
---|---|---|
3c775de6 | 1 | <?xml version='1.0'?> |
3a54a157 ZJS |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> | |
0307f791 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1+ --> |
3c775de6 ZJS |
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> | |
92b6df1d | 22 | <refname>sd_bus_is_anonymous</refname> |
3c775de6 | 23 | <refname>sd_bus_set_trusted</refname> |
92b6df1d | 24 | <refname>sd_bus_is_trusted</refname> |
3c775de6 ZJS |
25 | <refname>sd_bus_set_allow_interactive_authorization</refname> |
26 | <refname>sd_bus_get_allow_interactive_authorization</refname> | |
4eaf8bc6 DDM |
27 | <refname>sd_bus_get_scope</refname> |
28 | <refname>sd_bus_get_tid</refname> | |
29 | <refname>sd_bus_get_unique_name</refname> | |
3c775de6 ZJS |
30 | |
31 | <refpurpose>Set or query properties of a bus object</refpurpose> | |
32 | </refnamediv> | |
33 | ||
34 | <refsynopsisdiv> | |
35 | <funcsynopsis> | |
36 | <funcsynopsisinfo>#include <systemd/sd-bus.h></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 | ||
92b6df1d ZJS |
56 | <funcprototype> |
57 | <funcdef>int <function>sd_bus_is_anonymous</function></funcdef> | |
58 | <paramdef>sd_bus *<parameter>bus</parameter></paramdef> | |
59 | </funcprototype> | |
60 | ||
3c775de6 ZJS |
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 | ||
92b6df1d ZJS |
67 | <funcprototype> |
68 | <funcdef>int <function>sd_bus_is_trusted</function></funcdef> | |
69 | <paramdef>sd_bus *<parameter>bus</parameter></paramdef> | |
70 | </funcprototype> | |
71 | ||
3c775de6 ZJS |
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> | |
4eaf8bc6 DDM |
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> | |
3c775de6 ZJS |
100 | </funcsynopsis> |
101 | </refsynopsisdiv> | |
102 | ||
103 | <refsect1> | |
104 | <title>Description</title> | |
105 | ||
b778146b DDM |
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 | |
3c775de6 | 115 | <citerefentry><refentrytitle>sd_bus_open_with_description</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
b778146b DDM |
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>NULL</constant> otherwise.</para> | |
3c775de6 | 119 | |
b778146b DDM |
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> | |
3c775de6 | 125 | |
b778146b DDM |
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> | |
92b6df1d | 128 | |
3c775de6 | 129 | <para><function>sd_bus_set_trusted()</function> sets the "trusted" state on the |
b778146b DDM |
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> | |
3c775de6 | 133 | |
b778146b DDM |
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> | |
3c775de6 | 136 | |
b778146b DDM |
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 | |
3c775de6 | 139 | <constant>ALLOW_INTERACTIVE_AUTHORIZATION</constant> flag specified by the |
b778146b DDM |
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="http://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> | |
4eaf8bc6 DDM |
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> | |
3c775de6 ZJS |
170 | </refsect1> |
171 | ||
172 | <refsect1> | |
173 | <title>Return Value</title> | |
174 | ||
cc46b9d9 DDM |
175 | <para>On success, these functions return a non-negative integer. On failure, they return a |
176 | negative errno-style error code.</para> | |
3c775de6 | 177 | |
b1de39de ZJS |
178 | <refsect2> |
179 | <title>Errors</title> | |
3c775de6 | 180 | |
b1de39de | 181 | <para>Returned errors may indicate the following problems:</para> |
3c775de6 | 182 | |
b1de39de ZJS |
183 | <variablelist> |
184 | <varlistentry> | |
185 | <term><constant>-EINVAL</constant></term> | |
3c775de6 | 186 | |
b1de39de ZJS |
187 | <listitem><para>An argument is invalid.</para></listitem> |
188 | </varlistentry> | |
3c775de6 | 189 | |
b1de39de ZJS |
190 | <varlistentry> |
191 | <term><constant>-ENOPKG</constant></term> | |
3c775de6 | 192 | |
b1de39de ZJS |
193 | <listitem><para>The bus cannot be resolved.</para></listitem> |
194 | </varlistentry> | |
3c775de6 | 195 | |
b1de39de ZJS |
196 | <varlistentry> |
197 | <term><constant>-EPERM</constant></term> | |
3c775de6 | 198 | |
b1de39de ZJS |
199 | <listitem><para>The bus has already been started.</para></listitem> |
200 | </varlistentry> | |
3c775de6 | 201 | |
b1de39de ZJS |
202 | <varlistentry> |
203 | <term><constant>-ECHILD</constant></term> | |
3c775de6 | 204 | |
b1de39de ZJS |
205 | <listitem><para>The bus was created in a different process.</para></listitem> |
206 | </varlistentry> | |
3c775de6 | 207 | |
b1de39de ZJS |
208 | <varlistentry> |
209 | <term><constant>-ENOMEM</constant></term> | |
3c775de6 | 210 | |
b1de39de ZJS |
211 | <listitem><para>Memory allocation failed.</para></listitem> |
212 | </varlistentry> | |
3c775de6 | 213 | |
4eaf8bc6 DDM |
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></listitem> | |
226 | </varlistentry> | |
227 | </variablelist> | |
b1de39de | 228 | </refsect2> |
3c775de6 ZJS |
229 | </refsect1> |
230 | ||
231 | <xi:include href="libsystemd-pkgconfig.xml" /> | |
232 | ||
233 | <refsect1> | |
234 | <title>See Also</title> | |
235 | ||
236 | <para> | |
237 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
238 | <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
239 | <citerefentry><refentrytitle>sd_bus_default_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
240 | <citerefentry><refentrytitle>sd_bus_default_system</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
241 | <citerefentry><refentrytitle>sd_bus_open_user</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
242 | <citerefentry><refentrytitle>sd_bus_open_system</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
243 | </para> | |
244 | </refsect1> | |
245 | ||
246 | </refentry> |