Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_error.3

raw
1 '\" t
2 .TH "SD_BUS_ERROR" "3" "" "systemd 261~rc3" "sd_bus_error"
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_error, SD_BUS_ERROR_MAKE_CONST, SD_BUS_ERROR_NULL, sd_bus_error_free, sd_bus_error_set, sd_bus_error_setf, sd_bus_error_setfv, sd_bus_error_set_const, sd_bus_error_set_errno, sd_bus_error_set_errnof, sd_bus_error_set_errnofv, sd_bus_error_get_errno, sd_bus_error_copy, sd_bus_error_move, sd_bus_error_is_set, sd_bus_error_has_name, sd_bus_error_has_names_sentinel, sd_bus_error_has_names \- sd\-bus error handling
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 typedef struct {
35 const char *name;
36 const char *message;
37 \&...
38 } sd_bus_error;
39 .fi
40 .ft
41 .PP
42 \fBSD_BUS_ERROR_MAKE_CONST(\fR\fB\fIname\fR\fR\fB, \fR\fB\fImessage\fR\fR\fB)\fR
43 .PP
44 \fBSD_BUS_ERROR_NULL\fR
45 .HP \w'void\ sd_bus_error_free('u
46 .BI "void sd_bus_error_free(sd_bus_error\ *" "e" ");"
47 .HP \w'int\ sd_bus_error_set('u
48 .BI "int sd_bus_error_set(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "message" ");"
49 .HP \w'int\ sd_bus_error_setf('u
50 .BI "int sd_bus_error_setf(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "format" ", \&...);"
51 .HP \w'int\ sd_bus_error_setfv('u
52 .BI "int sd_bus_error_setfv(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "format" ", va_list\ " "ap" ");"
53 .HP \w'int\ sd_bus_error_set_const('u
54 .BI "int sd_bus_error_set_const(sd_bus_error\ *" "e" ", const\ char\ *" "name" ", const\ char\ *" "message" ");"
55 .HP \w'int\ sd_bus_error_set_errno('u
56 .BI "int sd_bus_error_set_errno(sd_bus_error\ *" "e" ", int\ " "error" ");"
57 .HP \w'int\ sd_bus_error_set_errnof('u
58 .BI "int sd_bus_error_set_errnof(sd_bus_error\ *" "e" ", int\ " "error" ", const\ char\ *" "format" ", \&...);"
59 .HP \w'int\ sd_bus_error_set_errnofv('u
60 .BI "int sd_bus_error_set_errnofv(sd_bus_error\ *" "e" ", int\ " "error" ", const\ char\ *" "format" ", va_list\ " "ap" ");"
61 .HP \w'int\ sd_bus_error_get_errno('u
62 .BI "int sd_bus_error_get_errno(const\ sd_bus_error\ *" "e" ");"
63 .HP \w'int\ sd_bus_error_copy('u
64 .BI "int sd_bus_error_copy(sd_bus_error\ *" "dst" ", const\ sd_bus_error\ *" "e" ");"
65 .HP \w'int\ sd_bus_error_move('u
66 .BI "int sd_bus_error_move(sd_bus_error\ *" "dst" ", sd_bus_error\ *" "e" ");"
67 .HP \w'int\ sd_bus_error_is_set('u
68 .BI "int sd_bus_error_is_set(const\ sd_bus_error\ *" "e" ");"
69 .HP \w'int\ sd_bus_error_has_name('u
70 .BI "int sd_bus_error_has_name(const\ sd_bus_error\ *" "e" ", const\ char\ *" "name" ");"
71 .HP \w'int\ sd_bus_error_has_names_sentinel('u
72 .BI "int sd_bus_error_has_names_sentinel(const\ sd_bus_error\ *" "e" ", \&.\&.\&.);"
73 .PP
74 #define sd_bus_error_has_names(e, \&.\&.\&.) sd_bus_error_has_names_sentinel(e, \&.\&.\&., NULL)
75 .SH "DESCRIPTION"
76 .PP
77 The
78 sd_bus_error
79 structure carries information about a D\-Bus error condition, or lack thereof\&. The functions described below may be used to set and query fields in this structure\&.
80 .sp
81 .RS 4
82 .ie n \{\
83 \h'-04'\(bu\h'+03'\c
84 .\}
85 .el \{\
86 .sp -1
87 .IP \(bu 2.3
88 .\}
89 The
90 \fIname\fR
91 field contains a short identifier of an error\&. It should follow the rules for error names described in the D\-Bus specification, subsection
92 \m[blue]\fBValid D\-Bus Names\fR\m[]\&\s-2\u[1]\d\s+2\&. A number of common, standardized error names are described in
93 \fBsd-bus-errors\fR(3), but additional domain\-specific errors may be defined by applications\&.
94 .RE
95 .sp
96 .RS 4
97 .ie n \{\
98 \h'-04'\(bu\h'+03'\c
99 .\}
100 .el \{\
101 .sp -1
102 .IP \(bu 2.3
103 .\}
104 The
105 \fImessage\fR
106 field usually contains a human\-readable string describing the details, but might be
107 \fBNULL\fR\&.
108 .RE
109 .sp
110 An unset
111 sd_bus_error
112 structure should have both fields initialized to
113 \fBNULL\fR, and signifies lack of an error, i\&.e\&. success\&. Assign
114 \fBSD_BUS_ERROR_NULL\fR
115 to the structure in order to initialize both fields to
116 \fBNULL\fR\&. When no longer necessary, resources held by the
117 sd_bus_error
118 structure should be destroyed with
119 \fBsd_bus_error_free()\fR\&.
120 .PP
121 \fBsd_bus_error_set()\fR
122 sets an error structure to the specified name and message strings\&. The strings will be copied into internal, newly allocated memory\&. It is essential to free the contents again when they are not required anymore (see above)\&. Do not use this call on error structures that have already been set\&. If you intend to reuse an error structure, free the old data stored in it with
123 \fBsd_bus_error_free()\fR
124 first\&.
125 .PP
126 \fBsd_bus_error_set()\fR
127 will return an
128 \fIerrno\fR\-like value (see
129 \fBerrno\fR(3)) determined from the specified error name
130 \fIname\fR\&. If
131 \fIname\fR
132 is
133 \fBNULL\fR, it is assumed that no error occurred, and
134 \fB0\fR
135 is returned\&. If
136 \fIname\fR
137 is nonnull, a negative value is always returned\&. If
138 \fIe\fR
139 is
140 \fBNULL\fR, no error structure is initialized, but
141 \fIname\fR
142 is still converted into an
143 \fIerrno\fR\-style value\&.
144 .PP
145 Various well\-known D\-Bus errors are converted to well\-known
146 \fIerrno\fR
147 counterparts, and the other ones to
148 \fB\-EIO\fR\&. See
149 \fBsd-bus-errors\fR(3)
150 for a list of well\-known error names\&. Additional error mappings may be defined with
151 \fBsd_bus_error_add_map\fR(3)\&.
152 .PP
153 \fBsd_bus_error_set()\fR
154 is designed to be conveniently used in a
155 \fBreturn\fR
156 statement\&. If
157 \fImessage\fR
158 is
159 \fBNULL\fR, no message is set\&. This call can fail if no memory may be allocated for the name and message strings, in which case an
160 \fBSD_BUS_ERROR_NO_MEMORY\fR
161 error will be set instead and
162 \fB\-ENOMEM\fR
163 returned\&.
164 .PP
165 \fBsd_bus_error_setf()\fR
166 and
167 \fBsd_bus_error_setfv()\fR
168 are similar to
169 \fBsd_bus_error_set()\fR, but take a
170 \fBprintf\fR(3)
171 format string and corresponding arguments to generate the
172 \fImessage\fR
173 field\&.
174 \fBsd_bus_error_setf()\fR
175 uses variadic arguments, and
176 \fBsd_bus_error_setfv()\fR
177 accepts the arguments as a
178 \fBva_arg\fR(3)
179 parameter list\&.
180 .PP
181 \fBsd_bus_error_set_const()\fR
182 is similar to
183 \fBsd_bus_error_set()\fR, but the string parameters are not copied internally, and must hence remain constant and valid for the lifetime of
184 \fIe\fR\&. Use this call to avoid memory allocations when setting error structures\&. Since this call does not allocate memory, it will not fail with an out\-of\-memory condition as
185 \fBsd_bus_error_set()\fR
186 may, as described above\&. Alternatively, the
187 \fBSD_BUS_ERROR_MAKE_CONST()\fR
188 macro may be used to generate a literal, constant bus error structure on\-the\-fly\&.
189 .PP
190 \fBsd_bus_error_set_errno()\fR
191 will immediately return
192 \fB0\fR
193 if the specified error parameter
194 \fIerror\fR
195 is
196 \fB0\fR\&. Otherwise, it will set
197 \fIname\fR
198 from an
199 \fIerrno\fR\-like value that is converted to a D\-Bus error\&.
200 \fBstrerror_r\fR(3)
201 will be used to set
202 \fImessage\fR\&. Well\-known D\-Bus error names will be used for
203 \fIname\fR
204 if applicable, otherwise a name in the
205 "System\&.Error\&."
206 namespace will be generated\&. The sign of the specified error number is ignored and the absolute value is used implicitly\&. If the specified error
207 \fIerror\fR
208 is non\-zero, the call always returns a negative value, for convenient usage in
209 \fBreturn\fR
210 statements\&. This call might fail due to lack of memory, in which case an
211 \fBSD_BUS_ERROR_NO_MEMORY\fR
212 error is set instead, and
213 \fB\-ENOMEM\fR
214 is returned\&.
215 .PP
216 \fBsd_bus_error_set_errnof()\fR
217 and
218 \fBsd_bus_error_set_errnof()\fR
219 are similar to
220 \fBsd_bus_error_set_errno()\fR, but in addition to
221 \fIerror\fR, take a
222 \fBprintf\fR(3)
223 format string and corresponding arguments\&. The
224 \fImessage\fR
225 field will be generated from
226 \fIformat\fR
227 and the arguments\&.
228 \fBsd_bus_error_set_errnof()\fR
229 uses variadic arguments, and
230 \fBsd_bus_error_set_errnofv()\fR
231 accepts the arguments as a
232 \fBva_arg\fR(3)
233 parameter list\&.
234 .PP
235 \fBsd_bus_error_get_errno()\fR
236 converts the
237 \fIname\fR
238 field of an error structure to an
239 \fIerrno\fR\-like (positive) value using the same rules as
240 \fBsd_bus_error_set()\fR\&. If
241 \fIe\fR
242 is
243 \fBNULL\fR,
244 \fB0\fR
245 will be returned\&.
246 .PP
247 \fBsd_bus_error_copy()\fR
248 will initialize
249 \fIdst\fR
250 using the values in
251 \fIe\fR, if
252 \fIe\fR
253 has been set with an error value before\&. Otherwise, it will return immediately\&. If the strings in
254 \fIe\fR
255 were set using
256 \fBsd_bus_error_set_const()\fR, they will be shared\&. Otherwise, they will be copied\&. Before this call,
257 \fIdst\fR
258 must be unset, i\&.e\&. either freshly initialized with
259 \fBNULL\fR
260 or reset using
261 \fBsd_bus_error_free()\fR\&.
262 .PP
263 \fBsd_bus_error_copy()\fR
264 generally returns
265 \fB0\fR
266 or a negative
267 \fIerrno\fR\-like value based on the input parameter
268 \fIe\fR:
269 \fB0\fR
270 if it was unset and a negative integer if it was set to some error, similarly to
271 \fBsd_bus_error_set()\fR\&. It may however also return an error generated internally, for example
272 \fB\-ENOMEM\fR
273 if a memory allocation fails\&.
274 .PP
275 \fBsd_bus_error_move()\fR
276 is similar to
277 \fBsd_bus_error_copy()\fR, but will move any error information from
278 \fIe\fR
279 into
280 \fIdst\fR, resetting the former\&. This function cannot fail, as no new memory is allocated\&. Note that if
281 \fIe\fR
282 is not set,
283 \fIdst\fR
284 is initialized to
285 \fBSD_BUS_ERROR_NULL\fR\&. Moreover, if
286 \fIdst\fR
287 is
288 \fBNULL\fR
289 no operation is executed on it and resources held by
290 \fIe\fR
291 are freed and reset\&. Returns a converted
292 \fIerrno\fR\-like, non\-positive error value\&.
293 .PP
294 \fBsd_bus_error_is_set()\fR
295 will return a non\-zero value if
296 \fIe\fR
297 is non\-\fBNULL\fR
298 and an error has been set,
299 \fBfalse\fR
300 otherwise\&.
301 .PP
302 \fBsd_bus_error_has_name()\fR
303 will return a non\-zero value if
304 \fIe\fR
305 is non\-\fBNULL\fR
306 and an error with the same
307 \fIname\fR
308 has been set,
309 \fBfalse\fR
310 otherwise\&.
311 .PP
312 \fBsd_bus_error_has_names_sentinel()\fR
313 is similar to
314 \fBsd_bus_error_has_name()\fR, but takes multiple names to check against\&. The list must be terminated with
315 \fBNULL\fR\&.
316 \fBsd_bus_error_has_names()\fR
317 is a macro wrapper around
318 \fBsd_bus_error_has_names_sentinel()\fR
319 that adds the
320 \fBNULL\fR
321 sentinel automatically\&.
322 .PP
323 \fBsd_bus_error_free()\fR
324 will destroy resources held by
325 \fIe\fR\&. The parameter itself will not be deallocated, and must be
326 \fBfree\fR(3)d by the caller if necessary\&. The function may also be called safely on unset errors (error structures with both fields set to
327 \fBNULL\fR), in which case it performs no operation\&. This call will reset the error structure after freeing the data, so that all fields are set to
328 \fBNULL\fR\&. The structure may be reused afterwards\&.
329 .SH "REFERENCE OWNERSHIP"
330 .PP
331 sd_bus_error
332 is not reference\-counted\&. Users should destroy resources held by it by calling
333 \fBsd_bus_error_free()\fR\&. Usually, error structures are allocated on the stack or passed in as function parameters, but they may also be allocated dynamically, in which case it is the duty of the caller to
334 \fBfree\fR(3)
335 the memory held by the structure itself after freeing its contents with
336 \fBsd_bus_error_free()\fR\&.
337 .SH "RETURN VALUE"
338 .PP
339 The functions
340 \fBsd_bus_error_set()\fR,
341 \fBsd_bus_error_setf()\fR, and
342 \fBsd_bus_error_set_const()\fR
343 always return
344 \fB0\fR
345 when the specified error value is
346 \fBNULL\fR, and a negative errno\-like value corresponding to the
347 \fIname\fR
348 parameter otherwise\&. The functions
349 \fBsd_bus_error_set_errno()\fR,
350 \fBsd_bus_error_set_errnof()\fR
351 and
352 \fBsd_bus_error_set_errnofv()\fR, return
353 \fB0\fR
354 when the specified error value is
355 \fB0\fR, and a negative errno\-like value corresponding to the
356 \fIerror\fR
357 parameter otherwise\&. If an error occurs internally, one of the negative error values listed below will be returned\&. This allows those functions to be conveniently used in a
358 \fBreturn\fR
359 statement, see the example below\&.
360 .PP
361 \fBsd_bus_error_get_errno()\fR
362 returns
363 \fBfalse\fR
364 when
365 \fIe\fR
366 is
367 \fBNULL\fR, and a positive errno value mapped from
368 \fIe\->name\fR
369 otherwise\&.
370 .PP
371 \fBsd_bus_error_copy()\fR
372 and
373 \fBsd_bus_error_move()\fR
374 return a negative error value converted from the source error, and zero if the error has not been set\&. This allows those functions to be conveniently used in a
375 \fBreturn\fR
376 statement, see the example below\&.
377 .PP
378 \fBsd_bus_error_is_set()\fR
379 returns a non\-zero value when
380 \fIe\fR
381 and the
382 \fIname\fR
383 field are non\-\fBNULL\fR, zero otherwise\&.
384 .PP
385 \fBsd_bus_error_has_name()\fR,
386 \fBsd_bus_error_has_names()\fR, and
387 \fBsd_bus_error_has_names_sentinel()\fR
388 return a non\-zero value when
389 \fIe\fR
390 is non\-\fBNULL\fR
391 and the
392 \fIname\fR
393 field is equal to one of the given names, zero otherwise\&.
394 .SS "Errors"
395 .PP
396 Return value may indicate the following problems in the invocation of the function itself:
397 .PP
398 \fB\-EINVAL\fR
399 .RS 4
400 Error was already set in the
401 sd_bus_error
402 structure when one the error\-setting functions was called\&.
403 .RE
404 .PP
405 \fB\-ENOMEM\fR
406 .RS 4
407 Memory allocation failed\&.
408 .RE
409 .PP
410 On success,
411 \fBsd_bus_error_set()\fR,
412 \fBsd_bus_error_setf()\fR,
413 \fBsd_bus_error_set_const()\fR,
414 \fBsd_bus_error_set_errno()\fR,
415 \fBsd_bus_error_set_errnof()\fR,
416 \fBsd_bus_error_set_errnofv()\fR,
417 \fBsd_bus_error_copy()\fR, and
418 \fBsd_bus_error_move()\fR
419 will return a negative converted
420 \fIerrno\fR\-style value, or
421 \fB0\fR
422 if the error parameter is
423 \fBNULL\fR
424 or unset\&. D\-Bus errors are converted to the integral
425 \fIerrno\fR\-style value, and the mapping mechanism is extensible, see the discussion above\&. This effectively means that almost any negative
426 \fIerrno\fR\-style value can be returned\&.
427 .SH "EXAMPLES"
428 .PP
429 \fBExample\ \&1.\ \&Using the negative return value to propagate an error\fR
430 .sp
431 .if n \{\
432 .RS 4
433 .\}
434 .nf
435 /* SPDX\-License\-Identifier: MIT\-0 */
436
437 #include <errno\&.h>
438 #include <string\&.h>
439 #include <unistd\&.h>
440 #include <systemd/sd\-bus\&.h>
441
442 int writer_with_negative_errno_return(int fd, sd_bus_error *error) {
443 const char *message = "Hello, World!\en";
444
445 ssize_t n = write(fd, message, strlen(message));
446 if (n >= 0)
447 return n; /* On success, return the number of bytes written, possibly 0\&. */
448
449 /* On error, initialize the error structure, and also propagate the errno
450 * value that write(2) set for us\&. */
451 return sd_bus_error_set_errnof(error, errno, "Failed to write to fd %i: %s", fd, strerror(errno));
452 }
453 .fi
454 .if n \{\
455 .RE
456 .\}
457 .SH "NOTES"
458 .PP
459 Functions described here are available as a shared library, which can be compiled against and linked to with the
460 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
461 file\&.
462 .PP
463 The code described here uses
464 \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
465 \fBsetenv\fR(3)
466 from a parallel thread\&. It is recommended to only do calls to
467 \fBsetenv()\fR
468 from an early phase of the program when no other threads have been started\&.
469 .SH "HISTORY"
470 .PP
471 \fBsd_bus_error_free()\fR,
472 \fBsd_bus_error_set()\fR,
473 \fBsd_bus_error_setf()\fR,
474 \fBsd_bus_error_set_const()\fR,
475 \fBsd_bus_error_set_errno()\fR,
476 \fBsd_bus_error_set_errnof()\fR,
477 \fBsd_bus_error_set_errnofv()\fR,
478 \fBsd_bus_error_get_errno()\fR,
479 \fBsd_bus_error_copy()\fR,
480 \fBsd_bus_error_is_set()\fR, and
481 \fBsd_bus_error_has_name()\fR
482 were added in version 221\&.
483 .PP
484 \fBsd_bus_error_move()\fR
485 was added in version 240\&.
486 .PP
487 \fBsd_bus_error_has_names_sentinel()\fR
488 was added in version 247\&.
489 .PP
490 \fBsd_bus_error_setfv()\fR
491 was added in version 252\&.
492 .SH "SEE ALSO"
493 .PP
494 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd-bus-errors\fR(3), \fBsd_bus_error_add_map\fR(3), \fBerrno\fR(3), \fBstrerror_r\fR(3)
495 .SH "NOTES"
496 .IP " 1." 4
497 Valid D-Bus Names
498 .RS 4
499 \%https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names
500 .RE