2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"sd_bus_error" xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>sd_bus_error
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>sd_bus_error
</refentrytitle>
15 <manvolnum>3</manvolnum>
19 <refname>sd_bus_error
</refname>
20 <refname>SD_BUS_ERROR_MAKE_CONST
</refname>
21 <refname>SD_BUS_ERROR_NULL
</refname>
22 <refname>sd_bus_error_free
</refname>
23 <refname>sd_bus_error_set
</refname>
24 <refname>sd_bus_error_setf
</refname>
25 <refname>sd_bus_error_setfv
</refname>
26 <refname>sd_bus_error_set_const
</refname>
27 <refname>sd_bus_error_set_errno
</refname>
28 <refname>sd_bus_error_set_errnof
</refname>
29 <refname>sd_bus_error_set_errnofv
</refname>
30 <refname>sd_bus_error_get_errno
</refname>
31 <refname>sd_bus_error_copy
</refname>
32 <refname>sd_bus_error_move
</refname>
33 <refname>sd_bus_error_is_set
</refname>
34 <refname>sd_bus_error_has_name
</refname>
35 <refname>sd_bus_error_has_names_sentinel
</refname>
36 <refname>sd_bus_error_has_names
</refname>
38 <refpurpose>sd-bus error handling
</refpurpose>
43 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
45 <funcsynopsisinfo>typedef struct {
49 } sd_bus_error;
</funcsynopsisinfo>
53 <constant>SD_BUS_ERROR_MAKE_CONST(
<replaceable>name
</replaceable>,
<replaceable>message
</replaceable>)
</constant>
56 <constant>SD_BUS_ERROR_NULL
</constant>
61 <funcdef>void
<function>sd_bus_error_free
</function></funcdef>
62 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
66 <funcdef>int
<function>sd_bus_error_set
</function></funcdef>
67 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
68 <paramdef>const char *
<parameter>name
</parameter></paramdef>
69 <paramdef>const char *
<parameter>message
</parameter></paramdef>
73 <funcdef>int
<function>sd_bus_error_setf
</function></funcdef>
74 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
75 <paramdef>const char *
<parameter>name
</parameter></paramdef>
76 <paramdef>const char *
<parameter>format
</parameter></paramdef>
77 <paramdef>…
</paramdef>
81 <funcdef>int
<function>sd_bus_error_setfv
</function></funcdef>
82 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
83 <paramdef>const char *
<parameter>name
</parameter></paramdef>
84 <paramdef>const char *
<parameter>format
</parameter></paramdef>
85 <paramdef>va_list
<parameter>ap
</parameter></paramdef>
89 <funcdef>int
<function>sd_bus_error_set_const
</function></funcdef>
90 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
91 <paramdef>const char *
<parameter>name
</parameter></paramdef>
92 <paramdef>const char *
<parameter>message
</parameter></paramdef>
96 <funcdef>int
<function>sd_bus_error_set_errno
</function></funcdef>
97 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
98 <paramdef>int
<parameter>error
</parameter></paramdef>
102 <funcdef>int
<function>sd_bus_error_set_errnof
</function></funcdef>
103 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
104 <paramdef>int
<parameter>error
</parameter></paramdef>
105 <paramdef>const char *
<parameter>format
</parameter></paramdef>
106 <paramdef>…
</paramdef>
110 <funcdef>int
<function>sd_bus_error_set_errnofv
</function></funcdef>
111 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
112 <paramdef>int
<parameter>error
</parameter></paramdef>
113 <paramdef>const char *
<parameter>format
</parameter></paramdef>
114 <paramdef>va_list
<parameter>ap
</parameter></paramdef>
118 <funcdef>int
<function>sd_bus_error_get_errno
</function></funcdef>
119 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
123 <funcdef>int
<function>sd_bus_error_copy
</function></funcdef>
124 <paramdef>sd_bus_error *
<parameter>dst
</parameter></paramdef>
125 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
129 <funcdef>int
<function>sd_bus_error_move
</function></funcdef>
130 <paramdef>sd_bus_error *
<parameter>dst
</parameter></paramdef>
131 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
135 <funcdef>int
<function>sd_bus_error_is_set
</function></funcdef>
136 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
140 <funcdef>int
<function>sd_bus_error_has_name
</function></funcdef>
141 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
142 <paramdef>const char *
<parameter>name
</parameter></paramdef>
146 <funcdef>int
<function>sd_bus_error_has_names_sentinel
</function></funcdef>
147 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
148 <paramdef>...
</paramdef>
153 #define sd_bus_error_has_names(e, ...) sd_bus_error_has_names_sentinel(e, ..., NULL)
159 <title>Description
</title>
161 <para>The
<structname>sd_bus_error
</structname> structure carries information about a D-Bus error
162 condition, or lack thereof. The functions described below may be used to set and query fields in this
165 <listitem><para>The
<structfield>name
</structfield> field contains a short identifier of an error. It
166 should follow the rules for error names described in the D-Bus specification, subsection
<ulink
167 url=
"https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
168 D-Bus Names
</ulink>. A number of common, standardized error names are described in
169 <citerefentry><refentrytitle>sd-bus-errors
</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but
170 additional domain-specific errors may be defined by applications.
</para></listitem>
172 <listitem><para>The
<structfield>message
</structfield> field usually contains a human-readable string
173 describing the details, but might be
<constant>NULL
</constant>.
</para></listitem>
175 An unset
<structname>sd_bus_error
</structname> structure should have both fields initialized to
176 <constant>NULL
</constant>, and signifies lack of an error, i.e. success. Assign
177 <constant>SD_BUS_ERROR_NULL
</constant> to the structure in order to initialize both fields to
178 <constant>NULL
</constant>. When no longer necessary, resources held by the
179 <structname>sd_bus_error
</structname> structure should be destroyed with
180 <function>sd_bus_error_free()
</function>.
</para>
182 <para><function>sd_bus_error_set()
</function> sets an error structure to the specified name and message
183 strings. The strings will be copied into internal, newly allocated memory. It is essential to free the
184 contents again when they are not required anymore (see above). Do not use this call on error structures
185 that have already been set. If you intend to reuse an error structure, free the old data stored in it
186 with
<function>sd_bus_error_free()
</function> first.
</para>
188 <para><function>sd_bus_error_set()
</function> will return an
<varname>errno
</varname>-like value (see
190 project='man-pages'
><refentrytitle>errno
</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
191 determined from the specified error name
<parameter>name
</parameter>. If
<parameter>name
</parameter> is
192 <constant>NULL
</constant>, it is assumed that no error occurred, and
<constant>0</constant> is returned.
193 If
<parameter>name
</parameter> is nonnull, a negative value is always returned. If
194 <parameter>e
</parameter> is
<constant>NULL
</constant>, no error structure is initialized, but
195 <parameter>name
</parameter> is still converted into an
<varname>errno
</varname>-style value.
</para>
197 <para>Various well-known D-Bus errors are converted to well-known
<varname>errno
</varname> counterparts,
198 and the other ones to
<constant>-EIO
</constant>. See
199 <citerefentry><refentrytitle>sd-bus-errors
</refentrytitle><manvolnum>3</manvolnum></citerefentry> for a
200 list of well-known error names. Additional error mappings may be defined with
201 <citerefentry><refentrytitle>sd_bus_error_add_map
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
204 <para><function>sd_bus_error_set()
</function> is designed to be conveniently used in a
205 <function>return
</function> statement. If
<parameter>message
</parameter> is
<constant>NULL
</constant>, no
206 message is set. This call can fail if no memory may be allocated for the name and message strings, in
207 which case an
<constant>SD_BUS_ERROR_NO_MEMORY
</constant> error will be set instead and
208 <constant>-ENOMEM
</constant> returned.
</para>
210 <para><function>sd_bus_error_setf()
</function> and
<function>sd_bus_error_setfv()
</function> are similar
211 to
<function>sd_bus_error_set()
</function>, but take a
<citerefentry
212 project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry> format
213 string and corresponding arguments to generate the
<structfield>message
</structfield> field.
214 <function>sd_bus_error_setf()
</function> uses variadic arguments, and
215 <function>sd_bus_error_setfv()
</function> accepts the arguments as a
217 project='man-pages'
><refentrytitle>va_arg
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
218 parameter list.
</para>
220 <para><function>sd_bus_error_set_const()
</function> is similar to
221 <function>sd_bus_error_set()
</function>, but the string parameters are not copied internally, and must
222 hence remain constant and valid for the lifetime of
<parameter>e
</parameter>. Use this call to avoid
223 memory allocations when setting error structures. Since this call does not allocate memory, it will not
224 fail with an out-of-memory condition as
<function>sd_bus_error_set()
</function> may, as described
225 above. Alternatively, the
<constant>SD_BUS_ERROR_MAKE_CONST()
</constant> macro may be used to generate a
226 literal, constant bus error structure on-the-fly.
</para>
228 <para><function>sd_bus_error_set_errno()
</function> will immediately return
<constant>0</constant> if the
229 specified error parameter
<parameter>error
</parameter> is
<constant>0</constant>. Otherwise, it will set
230 <structfield>name
</structfield> from an
<varname>errno
</varname>-like value that is converted to a D-Bus
232 project='die-net'
><refentrytitle>strerror_r
</refentrytitle><manvolnum>3</manvolnum></citerefentry> will
233 be used to set
<structfield>message
</structfield>. Well-known D-Bus error names will be used for
234 <structfield>name
</structfield> if applicable, otherwise a name in the
<literal>System.Error.
</literal>
235 namespace will be generated. The sign of the specified error number is ignored and the absolute value is
236 used implicitly. If the specified error
<parameter>error
</parameter> is non-zero, the call always returns
237 a negative value, for convenient usage in
<function>return
</function> statements. This call might fail
238 due to lack of memory, in which case an
<constant>SD_BUS_ERROR_NO_MEMORY
</constant> error is set instead,
239 and
<constant>-ENOMEM
</constant> is returned.
</para>
241 <para><function>sd_bus_error_set_errnof()
</function> and
<function>sd_bus_error_set_errnof()
</function>
242 are similar to
<function>sd_bus_error_set_errno()
</function>, but in addition to
243 <parameter>error
</parameter>, take a
<citerefentry
244 project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry> format
245 string and corresponding arguments. The
<structfield>message
</structfield> field will be generated from
246 <parameter>format
</parameter> and the arguments.
247 <function>sd_bus_error_set_errnof()
</function> uses variadic arguments, and
248 <function>sd_bus_error_set_errnofv()
</function> accepts the arguments as a
250 project='man-pages'
><refentrytitle>va_arg
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
251 parameter list.
</para>
253 <para><function>sd_bus_error_get_errno()
</function> converts the
<structfield>name
</structfield> field of
254 an error structure to an
<varname>errno
</varname>-like (positive) value using the same rules as
255 <function>sd_bus_error_set()
</function>. If
<parameter>e
</parameter> is
<constant>NULL
</constant>,
256 <constant>0</constant> will be returned.
</para>
258 <para><function>sd_bus_error_copy()
</function> will initialize
<parameter>dst
</parameter> using the
259 values in
<parameter>e
</parameter>, if
<parameter>e
</parameter> has been set with an error value before.
260 Otherwise, it will return immediately. If the strings in
<parameter>e
</parameter> were set using
261 <function>sd_bus_error_set_const()
</function>, they will be shared. Otherwise, they will be
262 copied. Before this call,
<parameter>dst
</parameter> must be unset, i.e. either freshly initialized with
263 <constant>NULL
</constant> or reset using
<function>sd_bus_error_free()
</function>.
</para>
265 <para><function>sd_bus_error_copy()
</function> generally returns
<constant>0</constant> or a negative
266 <varname>errno
</varname>-like value based on the input parameter
<parameter>e
</parameter>:
267 <constant>0</constant> if it was unset and a negative integer if it was set to some error, similarly to
268 <function>sd_bus_error_set()
</function>. It may however also return an error generated internally, for
269 example
<constant>-ENOMEM
</constant> if a memory allocation fails.
</para>
271 <para><function>sd_bus_error_move()
</function> is similar to
<function>sd_bus_error_copy()
</function>,
272 but will move any error information from
<parameter>e
</parameter> into
<parameter>dst
</parameter>,
273 resetting the former. This function cannot fail, as no new memory is allocated. Note that if
274 <parameter>e
</parameter> is not set,
<parameter>dst
</parameter> is initialized to
275 <constant>SD_BUS_ERROR_NULL
</constant>. Moreover, if
<parameter>dst
</parameter> is
276 <constant>NULL
</constant> no operation is executed on it and resources held by
<parameter>e
</parameter>
277 are freed and reset. Returns a converted
<varname>errno
</varname>-like, non-positive error value.
</para>
279 <para><function>sd_bus_error_is_set()
</function> will return a
280 non-zero value if
<parameter>e
</parameter> is
281 non-
<constant>NULL
</constant> and an error has been set,
282 <constant>false
</constant> otherwise.
</para>
284 <para><function>sd_bus_error_has_name()
</function> will return a
285 non-zero value if
<parameter>e
</parameter> is
286 non-
<constant>NULL
</constant> and an error with the same
287 <parameter>name
</parameter> has been set,
288 <constant>false
</constant> otherwise.
</para>
290 <para><function>sd_bus_error_has_names_sentinel()
</function> is similar to
291 <function>sd_bus_error_has_name()
</function>, but takes multiple names to check against. The list must be
292 terminated with
<constant>NULL
</constant>.
<function>sd_bus_error_has_names()
</function>
293 is a macro wrapper around
<function>sd_bus_error_has_names_sentinel()
</function> that adds the
294 <constant>NULL
</constant> sentinel automatically.
</para>
296 <para><function>sd_bus_error_free()
</function> will destroy
297 resources held by
<parameter>e
</parameter>. The parameter itself
298 will not be deallocated, and must be
<citerefentry
299 project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
300 by the caller if necessary. The function may also be called safely
301 on unset errors (error structures with both fields set to
<constant>NULL
</constant>),
302 in which case it performs no operation. This call will reset the
303 error structure after freeing the data, so that all fields are set
304 to
<constant>NULL
</constant>. The structure may be reused afterwards.
</para>
308 <title>Reference ownership
</title>
310 <para><structname>sd_bus_error
</structname> is not reference-counted. Users should destroy resources held
311 by it by calling
<function>sd_bus_error_free()
</function>. Usually, error structures are allocated on the
312 stack or passed in as function parameters, but they may also be allocated dynamically, in which case it
313 is the duty of the caller to
<citerefentry
314 project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry> the memory
315 held by the structure itself after freeing its contents with
316 <function>sd_bus_error_free()
</function>.
</para>
320 <title>Return Value
</title>
322 <para>The functions
<function>sd_bus_error_set()
</function>,
<function>sd_bus_error_setf()
</function>,
323 and
<function>sd_bus_error_set_const()
</function> always return
<constant>0</constant> when the specified
324 error value is
<constant>NULL
</constant>, and a negative errno-like value corresponding to the
325 <parameter>name
</parameter> parameter otherwise. The functions
326 <function>sd_bus_error_set_errno()
</function>,
<function>sd_bus_error_set_errnof()
</function> and
327 <function>sd_bus_error_set_errnofv()
</function>, return
<constant>0</constant> when the specified error
328 value is
<constant>0</constant>, and a negative errno-like value corresponding to the
329 <parameter>error
</parameter> parameter otherwise. If an error occurs internally, one of the negative
330 error values listed below will be returned. This allows those functions to be conveniently used in a
331 <constant>return
</constant> statement, see the example below.
</para>
333 <para><function>sd_bus_error_get_errno()
</function> returns
334 <constant>false
</constant> when
<parameter>e
</parameter> is
335 <constant>NULL
</constant>, and a positive errno value mapped from
336 <parameter>e-
>name
</parameter> otherwise.
</para>
338 <para><function>sd_bus_error_copy()
</function> and
<function>sd_bus_error_move()
</function> return a
339 negative error value converted from the source error, and zero if the error has not been set. This
340 allows those functions to be conveniently used in a
<constant>return
</constant> statement, see the
341 example below.
</para>
343 <para><function>sd_bus_error_is_set()
</function> returns a
344 non-zero value when
<parameter>e
</parameter> and the
345 <structfield>name
</structfield> field are
346 non-
<constant>NULL
</constant>, zero otherwise.
</para>
348 <para><function>sd_bus_error_has_name()
</function>,
<function>sd_bus_error_has_names()
</function>, and
349 <function>sd_bus_error_has_names_sentinel()
</function> return a non-zero value when
<parameter>e
</parameter> is
350 non-
<constant>NULL
</constant> and the
<structfield>name
</structfield> field is equal to one of the given
351 names, zero otherwise.
</para>
354 <title>Errors
</title>
356 <para>Return value may indicate the following problems in the invocation of the function itself:
</para>
360 <term><constant>-EINVAL
</constant></term>
362 <listitem><para>Error was already set in the
<structname>sd_bus_error
</structname> structure when
363 one the error-setting functions was called.
</para></listitem>
367 <term><constant>-ENOMEM
</constant></term>
369 <listitem><para>Memory allocation failed.
</para></listitem>
373 <para>On success,
<function>sd_bus_error_set()
</function>,
<function>sd_bus_error_setf()
</function>,
374 <function>sd_bus_error_set_const()
</function>,
<function>sd_bus_error_set_errno()
</function>,
375 <function>sd_bus_error_set_errnof()
</function>,
<function>sd_bus_error_set_errnofv()
</function>,
376 <function>sd_bus_error_copy()
</function>, and
<function>sd_bus_error_move()
</function> will return a
377 negative converted
<varname>errno
</varname>-style value, or
<constant>0</constant> if the error
378 parameter is
<constant>NULL
</constant> or unset. D-Bus errors are converted to the integral
379 <varname>errno
</varname>-style value, and the mapping mechanism is extensible, see the discussion
380 above. This effectively means that almost any negative
<varname>errno
</varname>-style value can be
386 <title>Examples
</title>
389 <title>Using the negative return value to propagate an error
</title>
391 <programlisting><xi:include href=
"sd_bus_error-example.c" parse=
"text" /></programlisting>
395 <xi:include href=
"libsystemd-pkgconfig.xml" />
398 <title>History
</title>
399 <para><function>sd_bus_error_free()
</function>,
400 <function>sd_bus_error_set()
</function>,
401 <function>sd_bus_error_setf()
</function>,
402 <function>sd_bus_error_set_const()
</function>,
403 <function>sd_bus_error_set_errno()
</function>,
404 <function>sd_bus_error_set_errnof()
</function>,
405 <function>sd_bus_error_set_errnofv()
</function>,
406 <function>sd_bus_error_get_errno()
</function>,
407 <function>sd_bus_error_copy()
</function>,
408 <function>sd_bus_error_is_set()
</function>, and
409 <function>sd_bus_error_has_name()
</function> were added in version
221.
</para>
410 <para><function>sd_bus_error_move()
</function> was added in version
240.
</para>
411 <para><function>sd_bus_error_has_names_sentinel()
</function> was added in version
247.
</para>
412 <para><function>sd_bus_error_setfv()
</function> was added in version
252.
</para>
416 <title>See Also
</title>
418 <para><simplelist type=
"inline">
419 <member><citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
420 <member><citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
421 <member><citerefentry><refentrytitle>sd-bus-errors
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
422 <member><citerefentry><refentrytitle>sd_bus_error_add_map
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
423 <member><citerefentry project='man-pages'
><refentrytitle>errno
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
424 <member><citerefentry project='man-pages'
><refentrytitle>strerror_r
</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>