1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
9 <refentry id="sd_bus_error" xmlns:xi="http://www.w3.org/2001/XInclude">
12 <title>sd_bus_error</title>
13 <productname>systemd</productname>
17 <contrib>A monkey with a typewriter</contrib>
18 <firstname>Zbigniew</firstname>
19 <surname>Jędrzejewski-Szmek</surname>
20 <email>zbyszek@in.waw.pl</email>
26 <refentrytitle>sd_bus_error</refentrytitle>
27 <manvolnum>3</manvolnum>
31 <refname>sd_bus_error</refname>
32 <refname>SD_BUS_ERROR_MAKE_CONST</refname>
33 <refname>SD_BUS_ERROR_NULL</refname>
34 <refname>sd_bus_error_free</refname>
35 <refname>sd_bus_error_set</refname>
36 <refname>sd_bus_error_setf</refname>
37 <refname>sd_bus_error_set_const</refname>
38 <refname>sd_bus_error_set_errno</refname>
39 <refname>sd_bus_error_set_errnof</refname>
40 <refname>sd_bus_error_set_errnofv</refname>
41 <refname>sd_bus_error_get_errno</refname>
42 <refname>sd_bus_error_copy</refname>
43 <refname>sd_bus_error_is_set</refname>
44 <refname>sd_bus_error_has_name</refname>
46 <refpurpose>sd-bus error handling</refpurpose>
51 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
53 <funcsynopsisinfo>typedef struct {
57 } sd_bus_error;</funcsynopsisinfo>
60 <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant>
63 <constant>SD_BUS_ERROR_NULL</constant>
67 <funcdef>void <function>sd_bus_error_free</function></funcdef>
68 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
72 <funcdef>int <function>sd_bus_error_set</function></funcdef>
73 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
74 <paramdef>const char *<parameter>name</parameter></paramdef>
75 <paramdef>const char *<parameter>message</parameter></paramdef>
79 <funcdef>int <function>sd_bus_error_setf</function></funcdef>
80 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
81 <paramdef>const char *<parameter>name</parameter></paramdef>
82 <paramdef>const char *<parameter>format</parameter></paramdef>
83 <paramdef>…</paramdef>
87 <funcdef>int <function>sd_bus_error_set_const</function></funcdef>
88 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
89 <paramdef>const char *<parameter>name</parameter></paramdef>
90 <paramdef>const char *<parameter>message</parameter></paramdef>
94 <funcdef>int <function>sd_bus_error_set_errno</function></funcdef>
95 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
96 <paramdef>int <parameter>error</parameter></paramdef>
100 <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef>
101 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
102 <paramdef>int <parameter>error</parameter></paramdef>
103 <paramdef>const char *<parameter>format</parameter></paramdef>
104 <paramdef>…</paramdef>
108 <funcdef>int <function>sd_bus_error_set_errnofv</function></funcdef>
109 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
110 <paramdef>int <parameter>error</parameter></paramdef>
111 <paramdef>const char *<parameter>format</parameter></paramdef>
112 <paramdef>va_list ap</paramdef>
116 <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
117 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
121 <funcdef>int <function>sd_bus_error_copy</function></funcdef>
122 <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef>
123 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
127 <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
128 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
132 <funcdef>int <function>sd_bus_error_has_name</function></funcdef>
133 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
134 <paramdef>const char *<parameter>name</parameter></paramdef>
141 <title>Description</title>
143 <para>The <structname>sd_bus_error</structname> structure carries
144 information about a D-Bus error condition. The functions described
145 below may be used to set and query fields in this structure. The
146 <structfield>name</structfield> field contains a short identifier
147 of an error. It should follow the rules for error names described
148 in the D-Bus specification, subsection <ulink
149 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
150 Names</ulink>. A number of common, standardized error names are
152 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
153 but additional domain-specific errors may be defined by
154 applications. The <structfield>message</structfield> field usually
155 contains a human-readable string describing the details, but might
156 be NULL. An unset <structname>sd_bus_error</structname> structure
157 should have both fields initialized to NULL. Set an error
158 structure to <constant>SD_BUS_ERROR_NULL</constant> in order to
159 reset both fields to NULL. When no longer necessary, resources
160 held by the <structname>sd_bus_error</structname>structure should
161 be destroyed with <function>sd_bus_error_free()</function>.</para>
163 <para><function>sd_bus_error_set()</function> sets an error
164 structure to the specified name and message strings. The strings
165 will be copied into internal, newly allocated memory. It is
166 essential to free the error structure again when it is not
167 required anymore (see above). The function will return an
168 <varname>errno</varname>-like negative value (see <citerefentry
169 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
170 determined from the specified error name. Various well-known
171 D-Bus errors are converted to well-known <varname>errno</varname>
172 counterparts, and the other ones to <constant>-EIO</constant>. See
173 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>
174 for a list of well-known error names. Additional error mappings
176 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
177 <parameter>e</parameter> is NULL, no error structure is initialized,
178 but the error is still converted into an
179 <varname>errno</varname>-style error. If
180 <parameter>name</parameter> is <constant>NULL</constant>, it is
181 assumed that no error occurred, and 0 is returned. This means that
182 this function may be conveniently used in a
183 <function>return</function> statement. If
184 <parameter>message</parameter> is NULL, no message is set. This
185 call can fail if no memory may be allocated for the name and
186 message strings, in which case an
187 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set
188 instead and -ENOMEM be returned. Do not use this call on error
189 structures that are already initialized. If you intend to reuse an
190 error structure, free the old data stored in it with
191 <function>sd_bus_error_free()</function> first.</para>
193 <para><function>sd_bus_error_setf()</function> is similar to
194 <function>sd_bus_error_set()</function>, but takes a <citerefentry
195 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
196 format string and corresponding arguments to generate the
197 <structfield>message</structfield> field.</para>
199 <para><function>sd_bus_error_set_const()</function> is similar to
200 <function>sd_bus_error_set()</function>, but the string parameters
201 are not copied internally, and must hence remain constant and
202 valid for the lifetime of <parameter>e</parameter>. Use this call
203 to avoid memory allocations when setting error structures. Since
204 this call does not allocate memory, it will not fail with an
205 out-of-memory condition as
206 <function>sd_bus_error_set()</function> can, as described
207 above. Alternatively, the
208 <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used
209 to generate a literal, constant bus error structure
212 <para><function>sd_bus_error_set_errno()</function> will set
213 <structfield>name</structfield> from an
214 <varname>errno</varname>-like value that is converted to a D-Bus
216 project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
217 will be used to set <structfield>message</structfield>. Well-known
218 D-Bus error names will be used for <structfield>name</structfield>
219 if applicable, otherwise a name in the
220 <literal>System.Error.</literal> namespace will be generated. The
221 sign of the specified error number is ignored. The absolute value
222 is used implicitly. The call always returns a negative value, for
223 convenient usage in <function>return</function> statements. This
224 call might fail due to lack of memory, in which case an
225 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead,
226 and -ENOMEM is returned.</para>
228 <para><function>sd_bus_error_set_errnof()</function> is similar to
229 <function>sd_bus_error_set_errno()</function>, but in addition to
230 <parameter>error</parameter>, takes a <citerefentry
231 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
232 format string and corresponding arguments. The
233 <structfield>message</structfield> field will be generated from
234 <parameter>format</parameter> and the arguments.</para>
236 <para><function>sd_bus_error_set_errnofv()</function> is similar to
237 <function>sd_bus_error_set_errnof()</function>, but takes the
238 format string parameters as <citerefentry
239 project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
240 parameter list.</para>
242 <para><function>sd_bus_error_get_errno()</function> converts the
243 <structfield>name</structfield> field of an error structure to an
244 <varname>errno</varname>-like (positive) value using the same
245 rules as <function>sd_bus_error_set()</function>. If
246 <parameter>e</parameter> is <constant>NULL</constant>, 0 will be
249 <para><function>sd_bus_error_copy()</function> will initialize
250 <parameter>dst</parameter> using the values in
251 <parameter>e</parameter>. If the strings in
252 <parameter>e</parameter> were set using
253 <function>sd_bus_error_set_const()</function>, they will be shared.
254 Otherwise, they will be copied. Returns a converted
255 <varname>errno</varname>-like, negative error code.</para>
257 <para><function>sd_bus_error_is_set()</function> will return a
258 non-zero value if <parameter>e</parameter> is
259 non-<constant>NULL</constant> and an error has been set,
260 <constant>false</constant> otherwise.</para>
262 <para><function>sd_bus_error_has_name()</function> will return a
263 non-zero value if <parameter>e</parameter> is
264 non-<constant>NULL</constant> and an error with the same
265 <parameter>name</parameter> has been set,
266 <constant>false</constant> otherwise.</para>
268 <para><function>sd_bus_error_free()</function> will destroy
269 resources held by <parameter>e</parameter>. The parameter itself
270 will not be deallocated, and must be <citerefentry
271 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
272 by the caller if necessary. The function may also be called safely
273 on unset errors (error structures with both fields set to NULL),
274 in which case it performs no operation. This call will reset the
275 error structure after freeing the data, so that all fields are set
276 to NULL. The structure may be reused afterwards.</para>
280 <title>Return Value</title>
282 <para>The functions <function>sd_bus_error_set()</function>,
283 <function>sd_bus_error_setf()</function>, and
284 <function>sd_bus_error_set_const()</function>, when successful,
285 return the negative errno value corresponding to the
286 <parameter>name</parameter> parameter. The functions
287 <function>sd_bus_error_set_errno()</function>,
288 <function>sd_bus_error_set_errnof()</function> and
289 <function>sd_bus_error_set_errnofv()</function>, when successful,
290 return the negative value of the <parameter>error</parameter>
291 parameter. If an error occurs, one of the negative error values
292 listed below will be returned.</para>
294 <para><function>sd_bus_error_get_errno()</function> returns
295 <constant>false</constant> when <parameter>e</parameter> is
296 <constant>NULL</constant>, and a positive errno value mapped from
297 <parameter>e->name</parameter> otherwise.</para>
299 <para><function>sd_bus_error_copy()</function> returns 0 or a
300 positive integer on success, and a negative error value converted
301 from the error name otherwise.</para>
303 <para><function>sd_bus_error_is_set()</function> returns a
304 non-zero value when <parameter>e</parameter> and the
305 <structfield>name</structfield> field are
306 non-<constant>NULL</constant>, zero otherwise.</para>
308 <para><function>sd_bus_error_has_name()</function> returns a
309 non-zero value when <parameter>e</parameter> is
310 non-<constant>NULL</constant> and the
311 <structfield>name</structfield> field is equal to
312 <parameter>name</parameter>, zero otherwise.</para>
316 <title>Reference ownership</title>
317 <para><structname>sd_bus_error</structname> is not reference
318 counted. Users should destroy resources held by it by calling
319 <function>sd_bus_error_free()</function>. Usually, error structures
320 are allocated on the stack or passed in as function parameters,
321 but they may also be allocated dynamically, in which case it is
322 the duty of the caller to <citerefentry
323 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
324 the memory held by the structure itself after freeing its contents
325 with <function>sd_bus_error_free()</function>.</para>
329 <title>Errors</title>
331 <para>Returned errors may indicate the following problems:</para>
336 <term><constant>-EINVAL</constant></term>
338 <listitem><para>Error was already set in
339 <structname>sd_bus_error</structname> structure when one the
340 error-setting functions was called.</para></listitem>
344 <term><constant>-ENOMEM</constant></term>
346 <listitem><para>Memory allocation failed.</para></listitem>
351 <xi:include href="libelogind-pkgconfig.xml" />
354 <title>See Also</title>
357 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
358 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
359 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
360 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
361 <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
362 <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>