2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id=
"sd_bus_set_description" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
12 <title>sd_bus_set_description
</title>
13 <productname>systemd
</productname>
17 <refentrytitle>sd_bus_set_description
</refentrytitle>
18 <manvolnum>3</manvolnum>
22 <refname>sd_bus_set_description
</refname>
23 <refname>sd_bus_get_description
</refname>
24 <refname>sd_bus_set_anonymous
</refname>
25 <refname>sd_bus_set_trusted
</refname>
26 <refname>sd_bus_set_allow_interactive_authorization
</refname>
27 <refname>sd_bus_get_allow_interactive_authorization
</refname>
29 <refpurpose>Set or query properties of a bus object
</refpurpose>
34 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
37 <funcdef>int
<function>sd_bus_set_description
</function></funcdef>
38 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
39 <paramdef>const char *
<parameter>description
</parameter></paramdef>
43 <funcdef>int
<function>sd_bus_get_description
</function></funcdef>
44 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
45 <paramdef>const char **
<parameter>description
</parameter></paramdef>
49 <funcdef>int
<function>sd_bus_set_anonymous
</function></funcdef>
50 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
51 <paramdef>int
<parameter>b
</parameter></paramdef>
55 <funcdef>int
<function>sd_bus_set_trusted
</function></funcdef>
56 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
57 <paramdef>int
<parameter>b
</parameter></paramdef>
61 <funcdef>int
<function>sd_bus_set_allow_interactive_authorization
</function></funcdef>
62 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
63 <paramdef>int
<parameter>b
</parameter></paramdef>
67 <funcdef>int
<function>sd_bus_get_allow_interactive_authorization
</function></funcdef>
68 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
74 <title>Description
</title>
76 <para><function>sd_bus_set_description()
</function> sets the description string
77 that is used in logging to the specified string. The string is copied internally
78 and freed when the bus object is deallocated. The
79 <parameter>description
</parameter> argument may be
<constant>NULL
</constant>, in
80 which case the description is unset. This function must be called before the bus
81 has been started.
</para>
83 <para><function>sd_bus_get_description()
</function> returns a description string
84 in
<parameter>description
</parameter>. This string may have been previously set
85 with
<function>sd_bus_set_description()
</function> or
86 <citerefentry><refentrytitle>sd_bus_open_with_description
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
87 or similar. If not set this way, a default string like
<literal>system
</literal>
88 or
<literal>user
</literal> will be returned for the system or user buses,
89 and
<constant>NULL
</constant> otherwise.
</para>
91 <para><function>sd_bus_set_anonymous()
</function> enables or disables
"anonymous
92 authentication", i.e. lack of authentication, of the bus peer. This function must
93 be called before the bus has been started. See the
<ulink
94 url=
"view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">Authentication
95 Mechanisms
</ulink> section of the D-Bus specification for details.
</para>
97 <para><function>sd_bus_set_trusted()
</function> sets the
"trusted" state on the
98 <parameter>bus
</parameter> object. If true, all connections on the bus are
99 trusted and access to all privileged and unprivileged methods is granted. This
100 function must be called before the bus has been started.
</para>
102 <para><function>sd_bus_set_allow_interactive_authorization()
</function>
103 enables or disables interactive authorization for method calls. If true,
104 messages are marked with the
105 <constant>ALLOW_INTERACTIVE_AUTHORIZATION
</constant> flag specified by the
107 url=
"view-source:https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus
</ulink>
108 specification, informing the receiving side that the caller is prepared to
109 wait for interactive authorization, which might take a considerable time to
110 complete. If this flag is set, the user may be queried for passwords or
111 confirmation via
<ulink
112 url=
"http://www.freedesktop.org/wiki/Software/polkit">polkit
</ulink> or a
113 similar framework.
</para>
115 <para><function>sd_bus_get_allow_interactive_authorization()
</function> returns
116 true if interactive authorization is allowed and false if not.
</para>
120 <title>Return Value
</title>
122 <para>On success, these functions return
0 or a positive integer. On failure,
123 they return a negative errno-style error code.
</para>
127 <title>Errors
</title>
129 <para>Returned errors may indicate the following problems:
</para>
133 <term><constant>-EINVAL
</constant></term>
135 <listitem><para>An argument is invalid.
</para></listitem>
141 <term><constant>-ENOPKG
</constant></term>
143 <listitem><para>The bus cannot be resolved.
</para></listitem>
149 <term><constant>-EPERM
</constant></term>
151 <listitem><para>The bus has already been started.
</para></listitem>
157 <term><constant>-ECHILD
</constant></term>
159 <listitem><para>The bus was created in a different process.
</para></listitem>
165 <term><constant>-ENOMEM
</constant></term>
167 <listitem><para>Memory allocation failed.
</para></listitem>
173 <xi:include href=
"libsystemd-pkgconfig.xml" />
176 <title>See Also
</title>
179 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
180 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
181 <citerefentry><refentrytitle>sd_bus_default_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
182 <citerefentry><refentrytitle>sd_bus_default_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
183 <citerefentry><refentrytitle>sd_bus_open_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
184 <citerefentry><refentrytitle>sd_bus_open_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>