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+ -->
6 <refentry id=
"sd_bus_set_description" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>sd_bus_set_description
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>sd_bus_set_description
</refentrytitle>
15 <manvolnum>3</manvolnum>
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_set_trusted
</refname>
23 <refname>sd_bus_set_allow_interactive_authorization
</refname>
24 <refname>sd_bus_get_allow_interactive_authorization
</refname>
26 <refpurpose>Set or query properties of a bus object
</refpurpose>
31 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
34 <funcdef>int
<function>sd_bus_set_description
</function></funcdef>
35 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
36 <paramdef>const char *
<parameter>description
</parameter></paramdef>
40 <funcdef>int
<function>sd_bus_get_description
</function></funcdef>
41 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
42 <paramdef>const char **
<parameter>description
</parameter></paramdef>
46 <funcdef>int
<function>sd_bus_set_anonymous
</function></funcdef>
47 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
48 <paramdef>int
<parameter>b
</parameter></paramdef>
52 <funcdef>int
<function>sd_bus_set_trusted
</function></funcdef>
53 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
54 <paramdef>int
<parameter>b
</parameter></paramdef>
58 <funcdef>int
<function>sd_bus_set_allow_interactive_authorization
</function></funcdef>
59 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
60 <paramdef>int
<parameter>b
</parameter></paramdef>
64 <funcdef>int
<function>sd_bus_get_allow_interactive_authorization
</function></funcdef>
65 <paramdef>sd_bus *
<parameter>bus
</parameter></paramdef>
71 <title>Description
</title>
73 <para><function>sd_bus_set_description()
</function> sets the description string
74 that is used in logging to the specified string. The string is copied internally
75 and freed when the bus object is deallocated. The
76 <parameter>description
</parameter> argument may be
<constant>NULL
</constant>, in
77 which case the description is unset. This function must be called before the bus
78 has been started.
</para>
80 <para><function>sd_bus_get_description()
</function> returns a description string
81 in
<parameter>description
</parameter>. This string may have been previously set
82 with
<function>sd_bus_set_description()
</function> or
83 <citerefentry><refentrytitle>sd_bus_open_with_description
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
84 or similar. If not set this way, a default string like
<literal>system
</literal>
85 or
<literal>user
</literal> will be returned for the system or user buses,
86 and
<constant>NULL
</constant> otherwise.
</para>
88 <para><function>sd_bus_set_anonymous()
</function> enables or disables
"anonymous
89 authentication", i.e. lack of authentication, of the bus peer. This function must
90 be called before the bus has been started. See the
<ulink
91 url=
"view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">Authentication
92 Mechanisms
</ulink> section of the D-Bus specification for details.
</para>
94 <para><function>sd_bus_set_trusted()
</function> sets the
"trusted" state on the
95 <parameter>bus
</parameter> object. If true, all connections on the bus are
96 trusted and access to all privileged and unprivileged methods is granted. This
97 function must be called before the bus has been started.
</para>
99 <para><function>sd_bus_set_allow_interactive_authorization()
</function>
100 enables or disables interactive authorization for method calls. If true,
101 messages are marked with the
102 <constant>ALLOW_INTERACTIVE_AUTHORIZATION
</constant> flag specified by the
104 url=
"view-source:https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus
</ulink>
105 specification, informing the receiving side that the caller is prepared to
106 wait for interactive authorization, which might take a considerable time to
107 complete. If this flag is set, the user may be queried for passwords or
108 confirmation via
<ulink
109 url=
"http://www.freedesktop.org/wiki/Software/polkit">polkit
</ulink> or a
110 similar framework.
</para>
112 <para><function>sd_bus_get_allow_interactive_authorization()
</function> returns
113 true if interactive authorization is allowed and false if not.
</para>
117 <title>Return Value
</title>
119 <para>On success, these functions return
0 or a positive integer. On failure, they return a negative
120 errno-style error code.
</para>
123 <title>Errors
</title>
125 <para>Returned errors may indicate the following problems:
</para>
129 <term><constant>-EINVAL
</constant></term>
131 <listitem><para>An argument is invalid.
</para></listitem>
135 <term><constant>-ENOPKG
</constant></term>
137 <listitem><para>The bus cannot be resolved.
</para></listitem>
141 <term><constant>-EPERM
</constant></term>
143 <listitem><para>The bus has already been started.
</para></listitem>
147 <term><constant>-ECHILD
</constant></term>
149 <listitem><para>The bus was created in a different process.
</para></listitem>
153 <term><constant>-ENOMEM
</constant></term>
155 <listitem><para>Memory allocation failed.
</para></listitem>
162 <xi:include href=
"libsystemd-pkgconfig.xml" />
165 <title>See Also
</title>
168 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
169 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
170 <citerefentry><refentrytitle>sd_bus_default_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
171 <citerefentry><refentrytitle>sd_bus_default_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
172 <citerefentry><refentrytitle>sd_bus_open_user
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
173 <citerefentry><refentrytitle>sd_bus_open_system
</refentrytitle><manvolnum>3</manvolnum></citerefentry>