2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
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_set_const
</refname>
26 <refname>sd_bus_error_set_errno
</refname>
27 <refname>sd_bus_error_set_errnof
</refname>
28 <refname>sd_bus_error_set_errnofv
</refname>
29 <refname>sd_bus_error_get_errno
</refname>
30 <refname>sd_bus_error_copy
</refname>
31 <refname>sd_bus_error_move
</refname>
32 <refname>sd_bus_error_is_set
</refname>
33 <refname>sd_bus_error_has_name
</refname>
34 <refname>sd_bus_error_has_names_sentinel
</refname>
35 <refname>sd_bus_error_has_names
</refname>
37 <refpurpose>sd-bus error handling
</refpurpose>
42 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
44 <funcsynopsisinfo>typedef struct {
48 } sd_bus_error;
</funcsynopsisinfo>
51 <constant>SD_BUS_ERROR_MAKE_CONST(
<replaceable>name
</replaceable>,
<replaceable>message
</replaceable>)
</constant>
54 <constant>SD_BUS_ERROR_NULL
</constant>
58 <funcdef>void
<function>sd_bus_error_free
</function></funcdef>
59 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
63 <funcdef>int
<function>sd_bus_error_set
</function></funcdef>
64 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
65 <paramdef>const char *
<parameter>name
</parameter></paramdef>
66 <paramdef>const char *
<parameter>message
</parameter></paramdef>
70 <funcdef>int
<function>sd_bus_error_setf
</function></funcdef>
71 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
72 <paramdef>const char *
<parameter>name
</parameter></paramdef>
73 <paramdef>const char *
<parameter>format
</parameter></paramdef>
74 <paramdef>…
</paramdef>
78 <funcdef>int
<function>sd_bus_error_set_const
</function></funcdef>
79 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
80 <paramdef>const char *
<parameter>name
</parameter></paramdef>
81 <paramdef>const char *
<parameter>message
</parameter></paramdef>
85 <funcdef>int
<function>sd_bus_error_set_errno
</function></funcdef>
86 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
87 <paramdef>int
<parameter>error
</parameter></paramdef>
91 <funcdef>int
<function>sd_bus_error_set_errnof
</function></funcdef>
92 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
93 <paramdef>int
<parameter>error
</parameter></paramdef>
94 <paramdef>const char *
<parameter>format
</parameter></paramdef>
95 <paramdef>…
</paramdef>
99 <funcdef>int
<function>sd_bus_error_set_errnofv
</function></funcdef>
100 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
101 <paramdef>int
<parameter>error
</parameter></paramdef>
102 <paramdef>const char *
<parameter>format
</parameter></paramdef>
103 <paramdef>va_list
<parameter>ap
</parameter></paramdef>
107 <funcdef>int
<function>sd_bus_error_get_errno
</function></funcdef>
108 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
112 <funcdef>int
<function>sd_bus_error_copy
</function></funcdef>
113 <paramdef>sd_bus_error *
<parameter>dst
</parameter></paramdef>
114 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
118 <funcdef>int
<function>sd_bus_error_move
</function></funcdef>
119 <paramdef>sd_bus_error *
<parameter>dst
</parameter></paramdef>
120 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
124 <funcdef>int
<function>sd_bus_error_is_set
</function></funcdef>
125 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
129 <funcdef>int
<function>sd_bus_error_has_name
</function></funcdef>
130 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
131 <paramdef>const char *
<parameter>name
</parameter></paramdef>
135 <funcdef>int
<function>sd_bus_error_has_names_sentinel
</function></funcdef>
136 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
137 <paramdef>...
</paramdef>
141 #define sd_bus_error_has_names(e, ...) sd_bus_error_has_names_sentinel(e, ..., NULL)
148 <title>Description
</title>
150 <para>The
<structname>sd_bus_error
</structname> structure carries
151 information about a D-Bus error condition. The functions described
152 below may be used to set and query fields in this structure. The
153 <structfield>name
</structfield> field contains a short identifier
154 of an error. It should follow the rules for error names described
155 in the D-Bus specification, subsection
<ulink
156 url=
"http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
157 Names
</ulink>. A number of common, standardized error names are
159 <citerefentry><refentrytitle>sd-bus-errors
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
160 but additional domain-specific errors may be defined by
161 applications. The
<structfield>message
</structfield> field usually
162 contains a human-readable string describing the details, but might
163 be NULL. An unset
<structname>sd_bus_error
</structname> structure
164 should have both fields initialized to NULL. Set an error
165 structure to
<constant>SD_BUS_ERROR_NULL
</constant> in order to
166 reset both fields to NULL. When no longer necessary, resources
167 held by the
<structname>sd_bus_error
</structname> structure should
168 be destroyed with
<function>sd_bus_error_free()
</function>.
</para>
170 <para><function>sd_bus_error_set()
</function> sets an error
171 structure to the specified name and message strings. The strings
172 will be copied into internal, newly allocated memory. It is
173 essential to free the error structure again when it is not
174 required anymore (see above). The function will return an
175 <varname>errno
</varname>-like negative value (see
<citerefentry
176 project='man-pages'
><refentrytitle>errno
</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
177 determined from the specified error name. Various well-known
178 D-Bus errors are converted to well-known
<varname>errno
</varname>
179 counterparts, and the other ones to
<constant>-EIO
</constant>. See
180 <citerefentry><refentrytitle>sd-bus-errors
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
181 for a list of well-known error names. Additional error mappings
183 <citerefentry><refentrytitle>sd_bus_error_add_map
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
184 <parameter>e
</parameter> is NULL, no error structure is initialized,
185 but the error is still converted into an
186 <varname>errno
</varname>-style error. If
187 <parameter>name
</parameter> is
<constant>NULL
</constant>, it is
188 assumed that no error occurred, and
0 is returned. This means that
189 this function may be conveniently used in a
190 <function>return
</function> statement. If
191 <parameter>message
</parameter> is NULL, no message is set. This
192 call can fail if no memory may be allocated for the name and
193 message strings, in which case an
194 <constant>SD_BUS_ERROR_NO_MEMORY
</constant> error might be set
195 instead and -ENOMEM be returned. Do not use this call on error
196 structures that are already initialized. If you intend to reuse an
197 error structure, free the old data stored in it with
198 <function>sd_bus_error_free()
</function> first.
</para>
200 <para><function>sd_bus_error_setf()
</function> is similar to
201 <function>sd_bus_error_set()
</function>, but takes a
<citerefentry
202 project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
203 format string and corresponding arguments to generate the
204 <structfield>message
</structfield> field.
</para>
206 <para><function>sd_bus_error_set_const()
</function> is similar to
207 <function>sd_bus_error_set()
</function>, but the string parameters
208 are not copied internally, and must hence remain constant and
209 valid for the lifetime of
<parameter>e
</parameter>. Use this call
210 to avoid memory allocations when setting error structures. Since
211 this call does not allocate memory, it will not fail with an
212 out-of-memory condition as
213 <function>sd_bus_error_set()
</function> can, as described
214 above. Alternatively, the
215 <constant>SD_BUS_ERROR_MAKE_CONST()
</constant> macro may be used
216 to generate a literal, constant bus error structure
219 <para><function>sd_bus_error_set_errno()
</function> will set
220 <structfield>name
</structfield> from an
221 <varname>errno
</varname>-like value that is converted to a D-Bus
223 project='die-net'
><refentrytitle>strerror_r
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
224 will be used to set
<structfield>message
</structfield>. Well-known
225 D-Bus error names will be used for
<structfield>name
</structfield>
226 if applicable, otherwise a name in the
227 <literal>System.Error.
</literal> namespace will be generated. The
228 sign of the specified error number is ignored. The absolute value
229 is used implicitly. The call always returns a negative value, for
230 convenient usage in
<function>return
</function> statements. This
231 call might fail due to lack of memory, in which case an
232 <constant>SD_BUS_ERROR_NO_MEMORY
</constant> error is set instead,
233 and -ENOMEM is returned.
</para>
235 <para><function>sd_bus_error_set_errnof()
</function> is similar to
236 <function>sd_bus_error_set_errno()
</function>, but in addition to
237 <parameter>error
</parameter>, takes a
<citerefentry
238 project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
239 format string and corresponding arguments. The
240 <structfield>message
</structfield> field will be generated from
241 <parameter>format
</parameter> and the arguments.
</para>
243 <para><function>sd_bus_error_set_errnofv()
</function> is similar to
244 <function>sd_bus_error_set_errnof()
</function>, but takes the
245 format string parameters as
<citerefentry
246 project='man-pages'
><refentrytitle>va_arg
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
247 parameter list.
</para>
249 <para><function>sd_bus_error_get_errno()
</function> converts the
250 <structfield>name
</structfield> field of an error structure to an
251 <varname>errno
</varname>-like (positive) value using the same
252 rules as
<function>sd_bus_error_set()
</function>. If
253 <parameter>e
</parameter> is
<constant>NULL
</constant>,
0 will be
256 <para><function>sd_bus_error_copy()
</function> will initialize
257 <parameter>dst
</parameter> using the values in
258 <parameter>e
</parameter>. If the strings in
259 <parameter>e
</parameter> were set using
260 <function>sd_bus_error_set_const()
</function>, they will be shared.
261 Otherwise, they will be copied. Returns a converted
262 <varname>errno
</varname>-like, negative error code.
</para>
264 <para><function>sd_bus_error_move()
</function> is similar to
<function>sd_bus_error_copy()
</function>, but will
265 move any error information from
<parameter>e
</parameter> into
<parameter>dst
</parameter>, resetting the
266 former. This function cannot fail, as no new memory is allocated. Note that if
<parameter>e
</parameter> is not set
267 (or
<constant>NULL
</constant>)
<parameter>dst
</parameter> is initializated to
268 <constant>SD_BUS_ERROR_NULL
</constant>. Moreover, if
<parameter>dst
</parameter> is
<constant>NULL
</constant> no
269 operation is executed on it and and resources held by
<parameter>e
</parameter> are freed and reset. Returns a
270 converted
<varname>errno
</varname>-like, negative error code.
</para>
272 <para><function>sd_bus_error_is_set()
</function> will return a
273 non-zero value if
<parameter>e
</parameter> is
274 non-
<constant>NULL
</constant> and an error has been set,
275 <constant>false
</constant> otherwise.
</para>
277 <para><function>sd_bus_error_has_name()
</function> will return a
278 non-zero value if
<parameter>e
</parameter> is
279 non-
<constant>NULL
</constant> and an error with the same
280 <parameter>name
</parameter> has been set,
281 <constant>false
</constant> otherwise.
</para>
283 <para><function>sd_bus_error_has_names_sentinel()
</function> is similar to
284 <function>sd_bus_error_has_name()
</function>, but takes multiple names to check against. The list must be
285 terminated with
<constant>NULL
</constant>.
<function>sd_bus_error_has_names()
</function>
286 is a macro wrapper around
<function>sd_bus_error_has_names_sentinel()
</function> that adds the
287 <constant>NULL
</constant> sentinel automatically.
</para>
289 <para><function>sd_bus_error_free()
</function> will destroy
290 resources held by
<parameter>e
</parameter>. The parameter itself
291 will not be deallocated, and must be
<citerefentry
292 project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
293 by the caller if necessary. The function may also be called safely
294 on unset errors (error structures with both fields set to NULL),
295 in which case it performs no operation. This call will reset the
296 error structure after freeing the data, so that all fields are set
297 to NULL. The structure may be reused afterwards.
</para>
301 <title>Return Value
</title>
303 <para>The functions
<function>sd_bus_error_set()
</function>,
304 <function>sd_bus_error_setf()
</function>, and
305 <function>sd_bus_error_set_const()
</function>, when successful,
306 return the negative errno value corresponding to the
307 <parameter>name
</parameter> parameter. The functions
308 <function>sd_bus_error_set_errno()
</function>,
309 <function>sd_bus_error_set_errnof()
</function> and
310 <function>sd_bus_error_set_errnofv()
</function>, when successful,
311 return the negative value of the
<parameter>error
</parameter>
312 parameter. If an error occurs, one of the negative error values
313 listed below will be returned.
</para>
315 <para><function>sd_bus_error_get_errno()
</function> returns
316 <constant>false
</constant> when
<parameter>e
</parameter> is
317 <constant>NULL
</constant>, and a positive errno value mapped from
318 <parameter>e-
>name
</parameter> otherwise.
</para>
320 <para><function>sd_bus_error_copy()
</function> and
<function>sd_bus_error_move()
</function> return
0 or a positive
321 integer on success, and a negative error value converted from the error name otherwise.
</para>
323 <para><function>sd_bus_error_is_set()
</function> returns a
324 non-zero value when
<parameter>e
</parameter> and the
325 <structfield>name
</structfield> field are
326 non-
<constant>NULL
</constant>, zero otherwise.
</para>
328 <para><function>sd_bus_error_has_name()
</function>,
<function>sd_bus_error_has_names()
</function>, and
329 <function>sd_bus_error_has_names_sentinel()
</function> return a non-zero value when
<parameter>e
</parameter> is
330 non-
<constant>NULL
</constant> and the
<structfield>name
</structfield> field is equal to one of the given
331 names, zero otherwise.
</para>
335 <title>Reference ownership
</title>
336 <para><structname>sd_bus_error
</structname> is not reference
337 counted. Users should destroy resources held by it by calling
338 <function>sd_bus_error_free()
</function>. Usually, error structures
339 are allocated on the stack or passed in as function parameters,
340 but they may also be allocated dynamically, in which case it is
341 the duty of the caller to
<citerefentry
342 project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
343 the memory held by the structure itself after freeing its contents
344 with
<function>sd_bus_error_free()
</function>.
</para>
347 <title>Errors
</title>
349 <para>Returned errors may indicate the following problems:
</para>
354 <term><constant>-EINVAL
</constant></term>
356 <listitem><para>Error was already set in
<structname>sd_bus_error
</structname> structure when one
357 the error-setting functions was called.
</para></listitem>
361 <term><constant>-ENOMEM
</constant></term>
363 <listitem><para>Memory allocation failed.
</para></listitem>
369 <xi:include href=
"libsystemd-pkgconfig.xml" />
372 <title>See Also
</title>
375 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
376 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
377 <citerefentry><refentrytitle>sd-bus-errors
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
378 <citerefentry><refentrytitle>sd_bus_error_add_map
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
379 <citerefentry project='man-pages'
><refentrytitle>errno
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
380 <citerefentry project='die-net'
><refentrytitle>strerror_r
</refentrytitle><manvolnum>3</manvolnum></citerefentry>