Skip to content

Commit 3c775de

Browse files
keszybzkeszybz
committed
man: add sd_bus_set_description(3)
1 parent 6299410 commit 3c775de

File tree

3 files changed

+197
-0
lines changed

3 files changed

+197
-0
lines changed

‎man/rules/meson.build‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,14 @@ manpages = [
242242
'sd_bus_request_name_async'],
243243
''],
244244
['sd_bus_set_connected_signal', '3', ['sd_bus_get_connected_signal'], ''],
245+
['sd_bus_set_description',
246+
'3',
247+
['sd_bus_get_allow_interactive_authorization',
248+
'sd_bus_get_description',
249+
'sd_bus_set_allow_interactive_authorization',
250+
'sd_bus_set_anonymous',
251+
'sd_bus_set_trusted'],
252+
''],
245253
['sd_bus_set_sender', '3', ['sd_bus_get_sender'], ''],
246254
['sd_bus_set_watch_bind', '3', ['sd_bus_get_watch_bind'], ''],
247255
['sd_bus_slot_set_destroy_callback',

‎man/sd-bus.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@
7171
<citerefentry><refentrytitle>sd_bus_reply_method_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
7272
<citerefentry><refentrytitle>sd_bus_request_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
7373
<citerefentry><refentrytitle>sd_bus_set_connected_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
74+
<citerefentry><refentrytitle>sd_bus_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
7475
<citerefentry><refentrytitle>sd_bus_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
7576
<citerefentry><refentrytitle>sd_bus_set_watch_bind</refentrytitle><manvolnum>3</manvolnum></citerefentry>
7677
<citerefentry><refentrytitle>sd_bus_set_slot_destroy_callback</refentrytitle><manvolnum>3</manvolnum></citerefentry>,

‎man/sd_bus_set_description.xml‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
<?xml version='1.0'?>
2+
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3+
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4+
5+
<!--
6+
SPDX-License-Identifier: LGPL-2.1+
7+
-->
8+
9+
<refentry id="sd_bus_set_description" xmlns:xi="http://www.w3.org/2001/XInclude">
10+
11+
<refentryinfo>
12+
<title>sd_bus_set_description</title>
13+
<productname>systemd</productname>
14+
</refentryinfo>
15+
16+
<refmeta>
17+
<refentrytitle>sd_bus_set_description</refentrytitle>
18+
<manvolnum>3</manvolnum>
19+
</refmeta>
20+
21+
<refnamediv>
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>
28+
29+
<refpurpose>Set or query properties of a bus object</refpurpose>
30+
</refnamediv>
31+
32+
<refsynopsisdiv>
33+
<funcsynopsis>
34+
<funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
35+
36+
<funcprototype>
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>
40+
</funcprototype>
41+
42+
<funcprototype>
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>
46+
</funcprototype>
47+
48+
<funcprototype>
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>
52+
</funcprototype>
53+
54+
<funcprototype>
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>
58+
</funcprototype>
59+
60+
<funcprototype>
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>
64+
</funcprototype>
65+
66+
<funcprototype>
67+
<funcdef>int <function>sd_bus_get_allow_interactive_authorization</function></funcdef>
68+
<paramdef>sd_bus *<parameter>bus</parameter></paramdef>
69+
</funcprototype>
70+
</funcsynopsis>
71+
</refsynopsisdiv>
72+
73+
<refsect1>
74+
<title>Description</title>
75+
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>
82+
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>
90+
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>
96+
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>
101+
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
106+
<ulink
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>
114+
115+
<para><function>sd_bus_get_allow_interactive_authorization()</function> returns
116+
true if interactive authorization is allowed and false if not.</para>
117+
</refsect1>
118+
119+
<refsect1>
120+
<title>Return Value</title>
121+
122+
<para>On success, these functions return 0 or a positive integer. On failure,
123+
they return a negative errno-style error code.</para>
124+
</refsect1>
125+
126+
<refsect1>
127+
<title>Errors</title>
128+
129+
<para>Returned errors may indicate the following problems:</para>
130+
131+
<variablelist>
132+
<varlistentry>
133+
<term><constant>-EINVAL</constant></term>
134+
135+
<listitem><para>An argument is invalid.</para></listitem>
136+
</varlistentry>
137+
</variablelist>
138+
139+
<variablelist>
140+
<varlistentry>
141+
<term><constant>-ENOPKG</constant></term>
142+
143+
<listitem><para>The bus cannot be resolved.</para></listitem>
144+
</varlistentry>
145+
</variablelist>
146+
147+
<variablelist>
148+
<varlistentry>
149+
<term><constant>-EPERM</constant></term>
150+
151+
<listitem><para>The bus has already been started.</para></listitem>
152+
</varlistentry>
153+
</variablelist>
154+
155+
<variablelist>
156+
<varlistentry>
157+
<term><constant>-ECHILD</constant></term>
158+
159+
<listitem><para>The bus was created in a different process.</para></listitem>
160+
</varlistentry>
161+
</variablelist>
162+
163+
<variablelist>
164+
<varlistentry>
165+
<term><constant>-ENOMEM</constant></term>
166+
167+
<listitem><para>Memory allocation failed.</para></listitem>
168+
</varlistentry>
169+
</variablelist>
170+
171+
</refsect1>
172+
173+
<xi:include href="libsystemd-pkgconfig.xml" />
174+
175+
<refsect1>
176+
<title>See Also</title>
177+
178+
<para>
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>
185+
</para>
186+
</refsect1>
187+
188+
</refentry>

0 commit comments

Comments
 (0)