]>
Commit | Line | Data |
---|---|---|
3802a3d3 | 1 | <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*--> |
71365a77 ZJS |
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 | <!-- | |
5de0ccff | 6 | This file is part of systemd. |
71365a77 | 7 | |
5de0ccff | 8 | Copyright 2014 Zbigniew Jędrzejewski-Szmek |
71365a77 | 9 | |
5de0ccff ZJS |
10 | systemd is free software; you can redistribute it and/or modify it |
11 | under the terms of the GNU Lesser General Public License as published by | |
12 | the Free Software Foundation; either version 2.1 of the License, or | |
13 | (at your option) any later version. | |
71365a77 | 14 | |
5de0ccff ZJS |
15 | systemd is distributed in the hope that it will be useful, but |
16 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
18 | Lesser General Public License for more details. | |
71365a77 | 19 | |
5de0ccff ZJS |
20 | You should have received a copy of the GNU Lesser General Public License |
21 | along with systemd; If not, see <http://www.gnu.org/licenses/>. | |
71365a77 ZJS |
22 | --> |
23 | ||
7c071fda | 24 | <refentry id="sd_bus_error" conditional="ENABLE_KDBUS"> |
71365a77 ZJS |
25 | |
26 | <refentryinfo> | |
27 | <title>sd_bus_error</title> | |
28 | <productname>systemd</productname> | |
29 | ||
30 | <authorgroup> | |
31 | <author> | |
32 | <contrib>A monkey with a typewriter</contrib> | |
33 | <firstname>Zbigniew</firstname> | |
34 | <surname>Jędrzejewski-Szmek</surname> | |
35 | <email>zbyszek@in.waw.pl</email> | |
36 | </author> | |
37 | </authorgroup> | |
38 | </refentryinfo> | |
39 | ||
40 | <refmeta> | |
41 | <refentrytitle>sd_bus_error</refentrytitle> | |
42 | <manvolnum>3</manvolnum> | |
43 | </refmeta> | |
44 | ||
45 | <refnamediv> | |
46 | <refname>sd_bus_error</refname> | |
47 | <refname>sd_bus_error_free</refname> | |
48 | <refname>sd_bus_error_set</refname> | |
49 | <refname>sd_bus_error_set_const</refname> | |
50 | <refname>sd_bus_error_set_errno</refname> | |
51 | <refname>sd_bus_error_set_errnof</refname> | |
52 | <refname>sd_bus_error_get_errno</refname> | |
53 | <refname>sd_bus_error_copy</refname> | |
54 | <refname>sd_bus_error_is_set</refname> | |
55 | <refname>sd_bus_error_has_name</refname> | |
56 | ||
6bb648a1 | 57 | <refpurpose>sd-bus error handling</refpurpose> |
71365a77 ZJS |
58 | </refnamediv> |
59 | ||
60 | <refsynopsisdiv> | |
61 | <funcsynopsis> | |
62 | <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> | |
63 | ||
64 | <funcsynopsisinfo>typedef struct { | |
65 | const char *name; | |
66 | const char *message; | |
67 | ... | |
68 | } sd_bus_error;</funcsynopsisinfo> | |
69 | ||
70 | <para> | |
71 | <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant> | |
72 | </para> | |
73 | <para> | |
74 | <constant>SD_BUS_ERROR_NULL</constant> | |
75 | </para> | |
76 | ||
77 | <funcprototype> | |
78 | <funcdef>int <function>sd_bus_error_free</function></funcdef> | |
79 | <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> | |
80 | </funcprototype> | |
81 | ||
82 | <funcprototype> | |
83 | <funcdef>int <function>sd_bus_error_set</function></funcdef> | |
84 | <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> | |
85 | <paramdef>const char *<parameter>name</parameter></paramdef> | |
86 | <paramdef>const char *<parameter>message</parameter></paramdef> | |
87 | </funcprototype> | |
88 | ||
89 | <funcprototype> | |
90 | <funcdef>int <function>sd_bus_error_setf</function></funcdef> | |
91 | <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> | |
92 | <paramdef>const char *<parameter>name</parameter></paramdef> | |
93 | <paramdef>const char *<parameter>format</parameter></paramdef> | |
94 | <paramdef>...</paramdef> | |
95 | </funcprototype> | |
96 | ||
97 | <funcprototype> | |
98 | <funcdef>int <function>sd_bus_error_set_const</function></funcdef> | |
99 | <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> | |
100 | <paramdef>const char *<parameter>name</parameter></paramdef> | |
101 | <paramdef>const char *<parameter>message</parameter></paramdef> | |
102 | </funcprototype> | |
103 | ||
104 | <funcprototype> | |
105 | <funcdef>int <function>sd_bus_error_set_errno</function></funcdef> | |
106 | <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> | |
107 | <paramdef>int <parameter>error</parameter></paramdef> | |
108 | </funcprototype> | |
109 | ||
110 | <funcprototype> | |
111 | <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef> | |
112 | <paramdef>sd_bus_error *<parameter>e</parameter></paramdef> | |
113 | <paramdef>int <parameter>error</parameter></paramdef> | |
114 | <paramdef>const char *<parameter>format</parameter></paramdef> | |
115 | <paramdef>...</paramdef> | |
116 | </funcprototype> | |
117 | ||
118 | <funcprototype> | |
119 | <funcdef>int <function>sd_bus_error_get_errno</function></funcdef> | |
120 | <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> | |
121 | </funcprototype> | |
122 | ||
123 | <funcprototype> | |
124 | <funcdef>int <function>sd_bus_error_copy</function></funcdef> | |
125 | <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef> | |
126 | <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> | |
127 | </funcprototype> | |
128 | ||
129 | <funcprototype> | |
130 | <funcdef>int <function>sd_bus_error_is_set</function></funcdef> | |
131 | <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> | |
132 | </funcprototype> | |
133 | ||
134 | <funcprototype> | |
135 | <funcdef>int <function>sd_bus_error_has_name</function></funcdef> | |
136 | <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef> | |
137 | <paramdef>const char *<parameter>name</parameter></paramdef> | |
138 | </funcprototype> | |
139 | </funcsynopsis> | |
140 | ||
141 | <para> | |
142 | <constant>SD_BUS_ERROR_FAILED</constant> | |
143 | </para> | |
144 | <para> | |
145 | <constant>SD_BUS_ERROR_NO_MEMORY</constant> | |
146 | </para> | |
147 | <para> | |
148 | <constant>SD_BUS_ERROR_SERVICE_UNKNOWN</constant> | |
149 | </para> | |
150 | <para> | |
151 | <constant>SD_BUS_ERROR_NAME_HAS_NO_OWNER</constant> | |
152 | </para> | |
153 | <para> | |
154 | <constant>SD_BUS_ERROR_NO_REPLY</constant> | |
155 | </para> | |
156 | <para> | |
157 | <constant>SD_BUS_ERROR_IO_ERROR</constant> | |
158 | </para> | |
159 | <para> | |
160 | <constant>SD_BUS_ERROR_BAD_ADDRESS</constant> | |
161 | </para> | |
162 | <para> | |
163 | <constant>SD_BUS_ERROR_NOT_SUPPORTED</constant> | |
164 | </para> | |
165 | <para> | |
166 | <constant>SD_BUS_ERROR_LIMITS_EXCEEDED</constant> | |
167 | </para> | |
168 | <para> | |
169 | <constant>SD_BUS_ERROR_ACCESS_DENIED</constant> | |
170 | </para> | |
171 | <para> | |
172 | <constant>SD_BUS_ERROR_AUTH_FAILED</constant> | |
173 | </para> | |
174 | <para> | |
175 | <constant>SD_BUS_ERROR_NO_SERVER</constant> | |
176 | </para> | |
177 | <para> | |
178 | <constant>SD_BUS_ERROR_TIMEOUT</constant> | |
179 | </para> | |
180 | <para> | |
181 | <constant>SD_BUS_ERROR_NO_NETWORK</constant> | |
182 | </para> | |
183 | <para> | |
184 | <constant>SD_BUS_ERROR_ADDRESS_IN_USE</constant> | |
185 | </para> | |
186 | <para> | |
187 | <constant>SD_BUS_ERROR_DISCONNECTED</constant> | |
188 | </para> | |
189 | <para> | |
190 | <constant>SD_BUS_ERROR_INVALID_ARGS</constant> | |
191 | </para> | |
192 | <para> | |
193 | <constant>SD_BUS_ERROR_FILE_NOT_FOUND</constant> | |
194 | </para> | |
195 | <para> | |
196 | <constant>SD_BUS_ERROR_FILE_EXISTS</constant> | |
197 | </para> | |
198 | <para> | |
199 | <constant>SD_BUS_ERROR_UNKNOWN_METHOD</constant> | |
200 | </para> | |
201 | <para> | |
202 | <constant>SD_BUS_ERROR_UNKNOWN_OBJECT</constant> | |
203 | </para> | |
204 | <para> | |
205 | <constant>SD_BUS_ERROR_UNKNOWN_INTERFACE</constant> | |
206 | </para> | |
207 | <para> | |
208 | <constant>SD_BUS_ERROR_UNKNOWN_PROPERTY</constant> | |
209 | </para> | |
210 | <para> | |
211 | <constant>SD_BUS_ERROR_PROPERTY_READ_ONLY</constant> | |
212 | </para> | |
213 | <para> | |
214 | <constant>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</constant> | |
215 | </para> | |
216 | <para> | |
217 | <constant>SD_BUS_ERROR_INVALID_SIGNATURE</constant> | |
218 | </para> | |
219 | <para> | |
220 | <constant>SD_BUS_ERROR_INCONSISTENT_MESSAGE</constant> | |
221 | </para> | |
222 | <para> | |
223 | <constant>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</constant> | |
224 | </para> | |
225 | <para> | |
226 | <constant>SD_BUS_ERROR_MATCH_RULE_INVALID</constant> | |
227 | </para> | |
228 | ||
229 | </refsynopsisdiv> | |
230 | ||
231 | <refsect1> | |
232 | <title>Description</title> | |
233 | ||
66f756d4 | 234 | <para>The <structname>sd_bus_error</structname> structure carries |
b8bde116 JE |
235 | information for a <filename>sd-bus</filename> error. The |
236 | functions described below can be used to set and query fields in | |
66f756d4 | 237 | this structure. The <structfield>name</structfield> field contains a |
71365a77 ZJS |
238 | short identifier of an error. It should follow the rules for error |
239 | names described in the D-Bus specification, subsection <ulink | |
240 | url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid | |
241 | Names</ulink>. The <structfield>message</structfield> is a human | |
242 | readable string describing the details. When no longer necessary, | |
243 | resources held by this structure should be destroyed with | |
244 | <function>sd_bus_error_free</function>.</para> | |
245 | ||
246 | <para><function>sd_bus_error_set</function> will return an | |
247 | errno-like negative value returned based on parameter | |
248 | <parameter>name</parameter> (see | |
5aded369 | 249 | <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>). |
71365a77 ZJS |
250 | Various well-known D-Bus errors are converted to specific values, |
251 | and the remaining ones to <constant>-ENXIO</constant>. Well-known | |
252 | D-Bus error names are available as constants | |
253 | <constant>SD_BUS_ERROR_FAILED</constant>, etc., listed above. If | |
66f756d4 | 254 | <parameter>name</parameter> is <constant>NULL</constant>, it is |
06b643e7 | 255 | assumed that no error occurred, and 0 is returned. This means that |
71365a77 ZJS |
256 | this function may be conveniently used in a |
257 | <function>return</function> statement.</para> | |
258 | ||
259 | <para>If <parameter>e</parameter> is not | |
260 | <constant>NULL</constant>, <structfield>name</structfield> and | |
66f756d4 | 261 | <structfield>message</structfield> in the |
71365a77 | 262 | <structname>sd_bus_error</structname> structure |
66f756d4 | 263 | <parameter>e</parameter> points at will be filled in. As described above, |
71365a77 ZJS |
264 | <parameter>name</parameter> may be <constant>NULL</constant>, |
265 | which is treated as no error. Parameter | |
266 | <parameter>message</parameter> may also be | |
267 | <constant>NULL</constant>, in which case no message is specified. | |
268 | <function>sd_bus_error_set</function> will make internal copies of | |
269 | specified strings.</para> | |
270 | ||
271 | <para><function>sd_bus_error_setf</function> is similar to | |
272 | <function>sd_bus_error_set</function>, but takes a | |
5aded369 | 273 | <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
71365a77 ZJS |
274 | format string and corresponding arguments to generate |
275 | <structname>message</structname>.</para> | |
276 | ||
277 | <para><function>sd_bus_error_set_const</function> is similar to | |
278 | <function>sd_bus_error_set</function>, but string parameters are | |
279 | not copied internally, and must remain valid for the lifetime of | |
280 | <parameter>e</parameter>.</para> | |
281 | ||
282 | <para><function>sd_bus_error_set_errno</function> will set | |
283 | <structfield>name</structfield> based on an errno-like value. | |
c83478b9 | 284 | <citerefentry project='die-net'><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
71365a77 ZJS |
285 | will be used to set <structfield>message</structfield>. Well-known |
286 | D-Bus error names will be used for <structfield>name</structfield> | |
287 | if available, otherwise a name in the | |
288 | <literal>System.Error</literal> namespace will be generated. | |
289 | </para> | |
290 | ||
291 | <para><function>sd_bus_error_set_errnof</function> is similar to | |
292 | <function>sd_bus_error_set_errno</function>, but in addition to | |
293 | <parameter>name</parameter>, takes a | |
5aded369 | 294 | <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
71365a77 ZJS |
295 | format and corresponding arguments. |
296 | <structfield>name</structfield> will be generated from | |
297 | <parameter>format</parameter> and the arguments.</para> | |
298 | ||
f70ca25a | 299 | <para><function>sd_bus_error_get_errno</function> will convert |
3c8fa0fd | 300 | <structname>e->name</structname> to an errno-like value using the |
3860bb6d ZJS |
301 | same rules as <function>sd_bus_error_set</function>. If |
302 | <parameter>e</parameter> is <constant>NULL</constant>, 0 will be | |
303 | returned.</para> | |
71365a77 ZJS |
304 | |
305 | <para><function>sd_bus_error_copy</function> will initialize | |
306 | <parameter>dst</parameter> using the values in | |
307 | <parameter>e</parameter>. If the strings in | |
308 | <parameter>e</parameter> were set using | |
309 | <function>sd_bus_set_error_const</function>, they will be shared. | |
66f756d4 | 310 | Otherwise, they will be copied.</para> |
71365a77 ZJS |
311 | |
312 | <para><function>sd_bus_error_is_set</function> will return | |
313 | <constant>true</constant> if <parameter>e</parameter> is | |
314 | non-<constant>NULL</constant> and an error has been set, | |
315 | <constant>false</constant> otherwise.</para> | |
316 | ||
317 | <para><function>sd_bus_error_has_name</function> will return true | |
318 | if <parameter>e</parameter> is non-<constant>NULL</constant> and | |
319 | an error with the same <parameter>name</parameter> has been set, | |
320 | <constant>false</constant> otherwise.</para> | |
321 | ||
322 | <para><function>sd_bus_error_free</function> will destroy resources | |
323 | held by <parameter>e</parameter>. The parameter itself will not | |
324 | be deallocated, and must be | |
5aded369 | 325 | <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d |
71365a77 ZJS |
326 | by the caller if necessary.</para> |
327 | </refsect1> | |
328 | ||
329 | <refsect1> | |
330 | <title>Return Value</title> | |
331 | ||
332 | <para>Functions <function>sd_bus_error_set</function>, | |
333 | <function>sd_bus_error_setf</function>, | |
334 | <function>sd_bus_error_set_const</function>, when successful, | |
335 | return the negative errno value corresponding to the | |
336 | <parameter>name</parameter> parameter. Functions | |
337 | <function>sd_bus_error_set_errno</function> and | |
338 | <function>sd_bus_error_set_errnof</function>, when successful, | |
339 | return the value of the <parameter>errno</parameter> parameter. If | |
340 | an error occurs, one of the negative error values listed below | |
341 | will be returned.</para> | |
342 | ||
343 | <para><function>sd_bus_error_get_errno</function> returns | |
344 | <constant>false</constant> when <parameter>e</parameter> is | |
345 | <constant>NULL</constant>, and a positive errno value mapped from | |
3c8fa0fd | 346 | <parameter>e->name</parameter> otherwise.</para> |
71365a77 ZJS |
347 | |
348 | <para><function>sd_bus_error_copy</function> returns 0 or a | |
349 | positive integer on success, and one of the negative error values | |
350 | listed below otherwise.</para> | |
351 | ||
352 | <para><function>sd_bus_error_is_set</function> returns | |
353 | <constant>true</constant> when <parameter>e</parameter> and | |
3c8fa0fd | 354 | <parameter>e->name</parameter> are non-<constant>NULL</constant>, |
71365a77 ZJS |
355 | <constant>false</constant> otherwise.</para> |
356 | ||
357 | <para><function>sd_bus_error_has_name</function> returns | |
358 | <constant>true</constant> when <parameter>e</parameter> is | |
3c8fa0fd | 359 | non-<constant>NULL</constant> and <parameter>e->name</parameter> |
71365a77 ZJS |
360 | is equal to <parameter>name</parameter>, |
361 | <constant>false</constant> otherwise.</para> | |
362 | </refsect1> | |
363 | ||
364 | <refsect1> | |
365 | <title>Reference ownership</title> | |
366 | <para><structname>sd_bus_error</structname> is not reference | |
367 | counted. Users should destroy resources held by it by calling | |
368 | <function>sd_bus_error_free</function>.</para> | |
369 | </refsect1> | |
370 | ||
371 | <refsect1> | |
372 | <title>Errors</title> | |
373 | ||
374 | <para>Returned errors may indicate the following problems:</para> | |
375 | ||
376 | <variablelist> | |
377 | ||
378 | <varlistentry> | |
8474b70c | 379 | <term><constant>-EINVAL</constant></term> |
71365a77 ZJS |
380 | |
381 | <listitem><para>Error was already set in | |
382 | <structname>sd_bus_error</structname> structure when one the | |
383 | error-setting functions was called.</para></listitem> | |
384 | </varlistentry> | |
385 | ||
386 | <varlistentry> | |
8474b70c | 387 | <term><constant>-ENOMEM</constant></term> |
71365a77 ZJS |
388 | |
389 | <listitem><para>Memory allocation failed.</para></listitem> | |
390 | </varlistentry> | |
391 | </variablelist> | |
392 | </refsect1> | |
393 | ||
394 | <refsect1> | |
395 | <title>Notes</title> | |
396 | ||
397 | <para><function>sd_bus_set_error()</function> and other functions | |
398 | described here are available as a shared library, which can be | |
399 | compiled and linked to with the | |
5aded369 | 400 | <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
71365a77 ZJS |
401 | file.</para> |
402 | </refsect1> | |
403 | ||
404 | <refsect1> | |
405 | <title>See Also</title> | |
406 | ||
407 | <para> | |
408 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
409 | <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
5aded369 | 410 | <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>, |
c83478b9 | 411 | <citerefentry project='die-net'><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry> |
71365a77 ZJS |
412 | </para> |
413 | </refsect1> | |
414 | ||
415 | </refentry> |