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>
35 <refpurpose>sd-bus error handling
</refpurpose>
40 <funcsynopsisinfo>#include
<systemd/sd-bus.h
></funcsynopsisinfo>
42 <funcsynopsisinfo>typedef struct {
46 } sd_bus_error;
</funcsynopsisinfo>
49 <constant>SD_BUS_ERROR_MAKE_CONST(
<replaceable>name
</replaceable>,
<replaceable>message
</replaceable>)
</constant>
52 <constant>SD_BUS_ERROR_NULL
</constant>
56 <funcdef>void
<function>sd_bus_error_free
</function></funcdef>
57 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
61 <funcdef>int
<function>sd_bus_error_set
</function></funcdef>
62 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
63 <paramdef>const char *
<parameter>name
</parameter></paramdef>
64 <paramdef>const char *
<parameter>message
</parameter></paramdef>
68 <funcdef>int
<function>sd_bus_error_setf
</function></funcdef>
69 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
70 <paramdef>const char *
<parameter>name
</parameter></paramdef>
71 <paramdef>const char *
<parameter>format
</parameter></paramdef>
72 <paramdef>…
</paramdef>
76 <funcdef>int
<function>sd_bus_error_set_const
</function></funcdef>
77 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
78 <paramdef>const char *
<parameter>name
</parameter></paramdef>
79 <paramdef>const char *
<parameter>message
</parameter></paramdef>
83 <funcdef>int
<function>sd_bus_error_set_errno
</function></funcdef>
84 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
85 <paramdef>int
<parameter>error
</parameter></paramdef>
89 <funcdef>int
<function>sd_bus_error_set_errnof
</function></funcdef>
90 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
91 <paramdef>int
<parameter>error
</parameter></paramdef>
92 <paramdef>const char *
<parameter>format
</parameter></paramdef>
93 <paramdef>…
</paramdef>
97 <funcdef>int
<function>sd_bus_error_set_errnofv
</function></funcdef>
98 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
99 <paramdef>int
<parameter>error
</parameter></paramdef>
100 <paramdef>const char *
<parameter>format
</parameter></paramdef>
101 <paramdef>va_list
<parameter>ap
</parameter></paramdef>
105 <funcdef>int
<function>sd_bus_error_get_errno
</function></funcdef>
106 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
110 <funcdef>int
<function>sd_bus_error_copy
</function></funcdef>
111 <paramdef>sd_bus_error *
<parameter>dst
</parameter></paramdef>
112 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
116 <funcdef>int
<function>sd_bus_error_move
</function></funcdef>
117 <paramdef>sd_bus_error *
<parameter>dst
</parameter></paramdef>
118 <paramdef>sd_bus_error *
<parameter>e
</parameter></paramdef>
122 <funcdef>int
<function>sd_bus_error_is_set
</function></funcdef>
123 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
127 <funcdef>int
<function>sd_bus_error_has_name
</function></funcdef>
128 <paramdef>const sd_bus_error *
<parameter>e
</parameter></paramdef>
129 <paramdef>const char *
<parameter>name
</parameter></paramdef>
136 <title>Description
</title>
138 <para>The
<structname>sd_bus_error
</structname> structure carries
139 information about a D-Bus error condition. The functions described
140 below may be used to set and query fields in this structure. The
141 <structfield>name
</structfield> field contains a short identifier
142 of an error. It should follow the rules for error names described
143 in the D-Bus specification, subsection
<ulink
144 url=
"http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
145 Names
</ulink>. A number of common, standardized error names are
147 <citerefentry><refentrytitle>sd-bus-errors
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
148 but additional domain-specific errors may be defined by
149 applications. The
<structfield>message
</structfield> field usually
150 contains a human-readable string describing the details, but might
151 be NULL. An unset
<structname>sd_bus_error
</structname> structure
152 should have both fields initialized to NULL. Set an error
153 structure to
<constant>SD_BUS_ERROR_NULL
</constant> in order to
154 reset both fields to NULL. When no longer necessary, resources
155 held by the
<structname>sd_bus_error
</structname> structure should
156 be destroyed with
<function>sd_bus_error_free()
</function>.
</para>
158 <para><function>sd_bus_error_set()
</function> sets an error
159 structure to the specified name and message strings. The strings
160 will be copied into internal, newly allocated memory. It is
161 essential to free the error structure again when it is not
162 required anymore (see above). The function will return an
163 <varname>errno
</varname>-like negative value (see
<citerefentry
164 project='man-pages'
><refentrytitle>errno
</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
165 determined from the specified error name. Various well-known
166 D-Bus errors are converted to well-known
<varname>errno
</varname>
167 counterparts, and the other ones to
<constant>-EIO
</constant>. See
168 <citerefentry><refentrytitle>sd-bus-errors
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
169 for a list of well-known error names. Additional error mappings
171 <citerefentry><refentrytitle>sd_bus_error_add_map
</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
172 <parameter>e
</parameter> is NULL, no error structure is initialized,
173 but the error is still converted into an
174 <varname>errno
</varname>-style error. If
175 <parameter>name
</parameter> is
<constant>NULL
</constant>, it is
176 assumed that no error occurred, and
0 is returned. This means that
177 this function may be conveniently used in a
178 <function>return
</function> statement. If
179 <parameter>message
</parameter> is NULL, no message is set. This
180 call can fail if no memory may be allocated for the name and
181 message strings, in which case an
182 <constant>SD_BUS_ERROR_NO_MEMORY
</constant> error might be set
183 instead and -ENOMEM be returned. Do not use this call on error
184 structures that are already initialized. If you intend to reuse an
185 error structure, free the old data stored in it with
186 <function>sd_bus_error_free()
</function> first.
</para>
188 <para><function>sd_bus_error_setf()
</function> is similar to
189 <function>sd_bus_error_set()
</function>, but takes a
<citerefentry
190 project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
191 format string and corresponding arguments to generate the
192 <structfield>message
</structfield> field.
</para>
194 <para><function>sd_bus_error_set_const()
</function> is similar to
195 <function>sd_bus_error_set()
</function>, but the string parameters
196 are not copied internally, and must hence remain constant and
197 valid for the lifetime of
<parameter>e
</parameter>. Use this call
198 to avoid memory allocations when setting error structures. Since
199 this call does not allocate memory, it will not fail with an
200 out-of-memory condition as
201 <function>sd_bus_error_set()
</function> can, as described
202 above. Alternatively, the
203 <constant>SD_BUS_ERROR_MAKE_CONST()
</constant> macro may be used
204 to generate a literal, constant bus error structure
207 <para><function>sd_bus_error_set_errno()
</function> will set
208 <structfield>name
</structfield> from an
209 <varname>errno
</varname>-like value that is converted to a D-Bus
211 project='die-net'
><refentrytitle>strerror_r
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
212 will be used to set
<structfield>message
</structfield>. Well-known
213 D-Bus error names will be used for
<structfield>name
</structfield>
214 if applicable, otherwise a name in the
215 <literal>System.Error.
</literal> namespace will be generated. The
216 sign of the specified error number is ignored. The absolute value
217 is used implicitly. The call always returns a negative value, for
218 convenient usage in
<function>return
</function> statements. This
219 call might fail due to lack of memory, in which case an
220 <constant>SD_BUS_ERROR_NO_MEMORY
</constant> error is set instead,
221 and -ENOMEM is returned.
</para>
223 <para><function>sd_bus_error_set_errnof()
</function> is similar to
224 <function>sd_bus_error_set_errno()
</function>, but in addition to
225 <parameter>error
</parameter>, takes a
<citerefentry
226 project='man-pages'
><refentrytitle>printf
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
227 format string and corresponding arguments. The
228 <structfield>message
</structfield> field will be generated from
229 <parameter>format
</parameter> and the arguments.
</para>
231 <para><function>sd_bus_error_set_errnofv()
</function> is similar to
232 <function>sd_bus_error_set_errnof()
</function>, but takes the
233 format string parameters as
<citerefentry
234 project='man-pages'
><refentrytitle>va_arg
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
235 parameter list.
</para>
237 <para><function>sd_bus_error_get_errno()
</function> converts the
238 <structfield>name
</structfield> field of an error structure to an
239 <varname>errno
</varname>-like (positive) value using the same
240 rules as
<function>sd_bus_error_set()
</function>. If
241 <parameter>e
</parameter> is
<constant>NULL
</constant>,
0 will be
244 <para><function>sd_bus_error_copy()
</function> will initialize
245 <parameter>dst
</parameter> using the values in
246 <parameter>e
</parameter>. If the strings in
247 <parameter>e
</parameter> were set using
248 <function>sd_bus_error_set_const()
</function>, they will be shared.
249 Otherwise, they will be copied. Returns a converted
250 <varname>errno
</varname>-like, negative error code.
</para>
252 <para><function>sd_bus_error_move()
</function> is similar to
<function>sd_bus_error_copy()
</function>, but will
253 move any error information from
<parameter>e
</parameter> into
<parameter>dst
</parameter>, resetting the
254 former. This function cannot fail, as no new memory is allocated. Note that if
<parameter>e
</parameter> is not set
255 (or
<constant>NULL
</constant>)
<parameter>dst
</parameter> is initializated to
256 <constant>SD_BUS_ERROR_NULL
</constant>. Moreover, if
<parameter>dst
</parameter> is
<constant>NULL
</constant> no
257 operation is executed on it and and resources held by
<parameter>e
</parameter> are freed and reset. Returns a
258 converted
<varname>errno
</varname>-like, negative error code.
</para>
260 <para><function>sd_bus_error_is_set()
</function> will return a
261 non-zero value if
<parameter>e
</parameter> is
262 non-
<constant>NULL
</constant> and an error has been set,
263 <constant>false
</constant> otherwise.
</para>
265 <para><function>sd_bus_error_has_name()
</function> will return a
266 non-zero value if
<parameter>e
</parameter> is
267 non-
<constant>NULL
</constant> and an error with the same
268 <parameter>name
</parameter> has been set,
269 <constant>false
</constant> otherwise.
</para>
271 <para><function>sd_bus_error_free()
</function> will destroy
272 resources held by
<parameter>e
</parameter>. The parameter itself
273 will not be deallocated, and must be
<citerefentry
274 project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
275 by the caller if necessary. The function may also be called safely
276 on unset errors (error structures with both fields set to NULL),
277 in which case it performs no operation. This call will reset the
278 error structure after freeing the data, so that all fields are set
279 to NULL. The structure may be reused afterwards.
</para>
283 <title>Return Value
</title>
285 <para>The functions
<function>sd_bus_error_set()
</function>,
286 <function>sd_bus_error_setf()
</function>, and
287 <function>sd_bus_error_set_const()
</function>, when successful,
288 return the negative errno value corresponding to the
289 <parameter>name
</parameter> parameter. The functions
290 <function>sd_bus_error_set_errno()
</function>,
291 <function>sd_bus_error_set_errnof()
</function> and
292 <function>sd_bus_error_set_errnofv()
</function>, when successful,
293 return the negative value of the
<parameter>error
</parameter>
294 parameter. If an error occurs, one of the negative error values
295 listed below will be returned.
</para>
297 <para><function>sd_bus_error_get_errno()
</function> returns
298 <constant>false
</constant> when
<parameter>e
</parameter> is
299 <constant>NULL
</constant>, and a positive errno value mapped from
300 <parameter>e-
>name
</parameter> otherwise.
</para>
302 <para><function>sd_bus_error_copy()
</function> and
<function>sd_bus_error_move()
</function> return
0 or a positive
303 integer on success, and a negative error value converted from the error name otherwise.
</para>
305 <para><function>sd_bus_error_is_set()
</function> returns a
306 non-zero value when
<parameter>e
</parameter> and the
307 <structfield>name
</structfield> field are
308 non-
<constant>NULL
</constant>, zero otherwise.
</para>
310 <para><function>sd_bus_error_has_name()
</function> returns a
311 non-zero value when
<parameter>e
</parameter> is
312 non-
<constant>NULL
</constant> and the
313 <structfield>name
</structfield> field is equal to
314 <parameter>name
</parameter>, zero otherwise.
</para>
318 <title>Reference ownership
</title>
319 <para><structname>sd_bus_error
</structname> is not reference
320 counted. Users should destroy resources held by it by calling
321 <function>sd_bus_error_free()
</function>. Usually, error structures
322 are allocated on the stack or passed in as function parameters,
323 but they may also be allocated dynamically, in which case it is
324 the duty of the caller to
<citerefentry
325 project='man-pages'
><refentrytitle>free
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
326 the memory held by the structure itself after freeing its contents
327 with
<function>sd_bus_error_free()
</function>.
</para>
330 <title>Errors
</title>
332 <para>Returned errors may indicate the following problems:
</para>
337 <term><constant>-EINVAL
</constant></term>
339 <listitem><para>Error was already set in
<structname>sd_bus_error
</structname> structure when one
340 the error-setting functions was called.
</para></listitem>
344 <term><constant>-ENOMEM
</constant></term>
346 <listitem><para>Memory allocation failed.
</para></listitem>
352 <xi:include href=
"libsystemd-pkgconfig.xml" />
355 <title>See Also
</title>
358 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
359 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
360 <citerefentry><refentrytitle>sd-bus-errors
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
361 <citerefentry><refentrytitle>sd_bus_error_add_map
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
362 <citerefentry project='man-pages'
><refentrytitle>errno
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
363 <citerefentry project='die-net'
><refentrytitle>strerror_r
</refentrytitle><manvolnum>3</manvolnum></citerefentry>