Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_set_description.3

raw
1 '\" t
2 .TH "SD_BUS_SET_DESCRIPTION" "3" "" "systemd 261~rc3" "sd_bus_set_description"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_bus_set_description, sd_bus_get_description, sd_bus_set_anonymous, sd_bus_is_anonymous, sd_bus_set_trusted, sd_bus_is_trusted, sd_bus_set_allow_interactive_authorization, sd_bus_get_allow_interactive_authorization, sd_bus_get_scope, sd_bus_get_tid, sd_bus_get_unique_name \- Set or query properties of a bus object
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_set_description('u
32 .BI "int sd_bus_set_description(sd_bus\ *" "bus" ", const\ char\ *" "description" ");"
33 .HP \w'int\ sd_bus_get_description('u
34 .BI "int sd_bus_get_description(sd_bus\ *" "bus" ", const\ char\ **" "description" ");"
35 .HP \w'int\ sd_bus_set_anonymous('u
36 .BI "int sd_bus_set_anonymous(sd_bus\ *" "bus" ", int\ " "b" ");"
37 .HP \w'int\ sd_bus_is_anonymous('u
38 .BI "int sd_bus_is_anonymous(sd_bus\ *" "bus" ");"
39 .HP \w'int\ sd_bus_set_trusted('u
40 .BI "int sd_bus_set_trusted(sd_bus\ *" "bus" ", int\ " "b" ");"
41 .HP \w'int\ sd_bus_is_trusted('u
42 .BI "int sd_bus_is_trusted(sd_bus\ *" "bus" ");"
43 .HP \w'int\ sd_bus_set_allow_interactive_authorization('u
44 .BI "int sd_bus_set_allow_interactive_authorization(sd_bus\ *" "bus" ", int\ " "b" ");"
45 .HP \w'int\ sd_bus_get_allow_interactive_authorization('u
46 .BI "int sd_bus_get_allow_interactive_authorization(sd_bus\ *" "bus" ");"
47 .HP \w'int\ sd_bus_get_scope('u
48 .BI "int sd_bus_get_scope(sd_bus\ *" "bus" ", const\ char\ **" "scope" ");"
49 .HP \w'int\ sd_bus_get_tid('u
50 .BI "int sd_bus_get_tid(sd_bus\ *" "bus" ", pid_t\ *" "tid" ");"
51 .HP \w'int\ sd_bus_get_unique_name('u
52 .BI "int sd_bus_get_unique_name(sd_bus\ *" "bus" ", const\ char\ **" "unique" ");"
53 .SH "DESCRIPTION"
54 .PP
55 \fBsd_bus_set_description()\fR
56 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
57 \fIdescription\fR
58 argument may be
59 \fBNULL\fR, in which case the description is unset\&. This function must be called before the bus is started\&.
60 .PP
61 \fBsd_bus_get_description()\fR
62 returns a description string in
63 \fIdescription\fR\&. This string may have been previously set with
64 \fBsd_bus_set_description()\fR
65 or
66 \fBsd_bus_open_with_description\fR(3)
67 or similar\&. If not set this way, a default string like
68 "system"
69 or
70 "user"
71 will be returned for the system or user buses, and
72 \fB\-ENXIO\fR
73 otherwise\&.
74 .PP
75 \fBsd_bus_set_anonymous()\fR
76 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
77 \m[blue]\fBD\-Bus Authentication Mechanisms\fR\m[]\&\s-2\u[1]\d\s+2
78 section of the D\-Bus specification for details\&.
79 .PP
80 \fBsd_bus_is_anonymous()\fR
81 returns true if the bus connection allows anonymous authentication (in the sense described in previous paragraph)\&.
82 .PP
83 \fBsd_bus_set_trusted()\fR
84 sets the "trusted" state on the
85 \fIbus\fR
86 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\&.
87 .PP
88 \fBsd_bus_is_trusted()\fR
89 returns true if the bus connection is trusted (in the sense described in previous paragraph)\&.
90 .PP
91 \fBsd_bus_set_allow_interactive_authorization()\fR
92 enables or disables interactive authorization for method calls\&. If true, messages are marked with the
93 \fBALLOW_INTERACTIVE_AUTHORIZATION\fR
94 flag specified by the
95 \m[blue]\fBD\-Bus\fR\m[]\&\s-2\u[2]\d\s+2
96 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
97 \m[blue]\fBpolkit\fR\m[]\&\s-2\u[3]\d\s+2
98 or a similar framework\&.
99 .PP
100 \fBsd_bus_get_allow_interactive_authorization()\fR
101 returns true if interactive authorization is allowed and false if not\&.
102 .PP
103 \fBsd_bus_get_scope()\fR
104 stores the scope of the given bus object in
105 \fIscope\fR\&. The scope of the system bus is
106 "system"\&. The scope of a user session bus is
107 "user"\&. If the given bus object is not the system or a user session bus,
108 \fBsd_bus_get_scope()\fR
109 returns an error\&.
110 .PP
111 \fBsd_bus_get_tid()\fR
112 stores the kernel thread id of the thread associated with the given bus object in
113 \fItid\fR\&. If
114 \fIbus\fR
115 is a default bus object obtained by calling one of the functions of the
116 \fBsd_bus_default\fR(3)
117 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
118 \fIbus\fR
119 is not a default bus object and is not attached to an event loop,
120 \fBsd_bus_get_tid()\fR
121 returns an error\&.
122 .PP
123 \fBsd_bus_get_unique_name()\fR
124 stores the unique name of the bus object on the bus in
125 \fIunique\fR\&. See
126 \m[blue]\fBThe D\-Bus specification\fR\m[]\&\s-2\u[4]\d\s+2
127 for more information on bus names\&. Note that the caller does not own the string stored in
128 \fIunique\fR
129 and should not free it\&.
130 .SH "RETURN VALUE"
131 .PP
132 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
133 .SS "Errors"
134 .PP
135 Returned errors may indicate the following problems:
136 .PP
137 \fB\-EINVAL\fR
138 .RS 4
139 An argument is invalid\&.
140 .RE
141 .PP
142 \fB\-ENOPKG\fR
143 .RS 4
144 The bus cannot be resolved\&.
145 .RE
146 .PP
147 \fB\-EPERM\fR
148 .RS 4
149 The bus has already been started\&.
150 .RE
151 .PP
152 \fB\-ECHILD\fR
153 .RS 4
154 The bus was created in a different process, library or module instance\&.
155 .RE
156 .PP
157 \fB\-ENOMEM\fR
158 .RS 4
159 Memory allocation failed\&.
160 .RE
161 .PP
162 \fB\-ENODATA\fR
163 .RS 4
164 The bus object passed to
165 \fBsd_bus_get_scope()\fR
166 was not a system or user session bus\&.
167 .sp
168 Added in version 246\&.
169 .RE
170 .PP
171 \fB\-ENXIO\fR
172 .RS 4
173 The bus object passed to
174 \fBsd_bus_get_tid()\fR
175 was not a default bus object and is not attached to an event loop\&.
176 .sp
177 The bus object passed to
178 \fBsd_bus_get_description()\fR
179 did not have a
180 \fIdescription\fR\&.
181 .sp
182 Added in version 246\&.
183 .RE
184 .SH "NOTES"
185 .PP
186 Functions described here are available as a shared library, which can be compiled against and linked to with the
187 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
188 file\&.
189 .PP
190 The code described here uses
191 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
192 \fBsetenv\fR(3)
193 from a parallel thread\&. It is recommended to only do calls to
194 \fBsetenv()\fR
195 from an early phase of the program when no other threads have been started\&.
196 .SH "HISTORY"
197 .PP
198 \fBsd_bus_set_description()\fR,
199 \fBsd_bus_get_description()\fR,
200 \fBsd_bus_set_anonymous()\fR,
201 \fBsd_bus_set_trusted()\fR,
202 \fBsd_bus_set_allow_interactive_authorization()\fR, and
203 \fBsd_bus_get_allow_interactive_authorization()\fR
204 were added in version 240\&.
205 .PP
206 \fBsd_bus_is_anonymous()\fR,
207 \fBsd_bus_is_trusted()\fR,
208 \fBsd_bus_get_scope()\fR,
209 \fBsd_bus_get_tid()\fR, and
210 \fBsd_bus_get_unique_name()\fR
211 were added in version 246\&.
212 .SH "SEE ALSO"
213 .PP
214 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_default_user\fR(3), \fBsd_bus_default_system\fR(3), \fBsd_bus_open_user\fR(3), \fBsd_bus_open_system\fR(3)
215 .SH "NOTES"
216 .IP " 1." 4
217 D-Bus Authentication Mechanisms
218 .RS 4
219 \%view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms
220 .RE
221 .IP " 2." 4
222 D-Bus
223 .RS 4
224 \%view-source:https://dbus.freedesktop.org/doc/dbus-specification.html
225 .RE
226 .IP " 3." 4
227 polkit
228 .RS 4
229 \%https://www.freedesktop.org/wiki/Software/polkit
230 .RE
231 .IP " 4." 4
232 The D-Bus specification
233 .RS 4
234 \%https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus
235 .RE