1<?xml version='1.0'?>
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-or-later -->
5
6<refentry id="sd_bus_error" xmlns:xi="http://www.w3.org/2001/XInclude">
7
8  <refentryinfo>
9    <title>sd_bus_error</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>sd_bus_error</refentrytitle>
15    <manvolnum>3</manvolnum>
16  </refmeta>
17
18  <refnamediv>
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>
36
37    <refpurpose>sd-bus error handling</refpurpose>
38  </refnamediv>
39
40  <refsynopsisdiv>
41    <funcsynopsis>
42      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
43
44      <funcsynopsisinfo>typedef struct {
45        const char *name;
46        const char *message;
47        …
48} sd_bus_error;</funcsynopsisinfo>
49
50      <para>
51        <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant>
52      </para>
53      <para>
54        <constant>SD_BUS_ERROR_NULL</constant>
55      </para>
56
57      <funcprototype>
58        <funcdef>void <function>sd_bus_error_free</function></funcdef>
59        <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
60      </funcprototype>
61
62      <funcprototype>
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>
67      </funcprototype>
68
69      <funcprototype>
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>
75      </funcprototype>
76
77      <funcprototype>
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>
82      </funcprototype>
83
84      <funcprototype>
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>
88      </funcprototype>
89
90      <funcprototype>
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>
96      </funcprototype>
97
98      <funcprototype>
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>
104      </funcprototype>
105
106      <funcprototype>
107        <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
108        <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
109      </funcprototype>
110
111      <funcprototype>
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>
115      </funcprototype>
116
117      <funcprototype>
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>
121      </funcprototype>
122
123      <funcprototype>
124        <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
125        <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
126      </funcprototype>
127
128      <funcprototype>
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>
132      </funcprototype>
133
134      <funcprototype>
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>
138      </funcprototype>
139
140      <para>
141        &#35;define sd_bus_error_has_names(e, ...) sd_bus_error_has_names_sentinel(e, ..., NULL)
142      </para>
143    </funcsynopsis>
144
145  </refsynopsisdiv>
146
147  <refsect1>
148    <title>Description</title>
149
150    <para>The <structname>sd_bus_error</structname> structure carries information about a D-Bus error
151    condition, or lack thereof. The functions described below may be used to set and query fields in this
152    structure.
153    <itemizedlist>
154      <listitem><para>The <structfield>name</structfield> field contains a short identifier of an error. It
155      should follow the rules for error names described 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 described in
158      <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but
159      additional domain-specific errors may be defined by applications.</para></listitem>
160
161      <listitem><para>The <structfield>message</structfield> field usually contains a human-readable string
162      describing the details, but might be <constant>NULL</constant>.</para></listitem>
163    </itemizedlist>
164    An unset <structname>sd_bus_error</structname> structure should have both fields initialized to
165    <constant>NULL</constant>, and signifies lack of an error, i.e. success. Assign
166    <constant>SD_BUS_ERROR_NULL</constant> to the structure in order to initialize both fields to
167    <constant>NULL</constant>. When no longer necessary, resources held by the
168    <structname>sd_bus_error</structname> structure should be destroyed with
169    <function>sd_bus_error_free()</function>.</para>
170
171    <para><function>sd_bus_error_set()</function> sets an error structure to the specified name and message
172    strings. The strings will be copied into internal, newly allocated memory. It is essential to free the
173    contents again when they are not required anymore (see above). Do not use this call on error structures
174    that have already been set. If you intend to reuse an error structure, free the old data stored in it
175    with <function>sd_bus_error_free()</function> first.</para>
176
177    <para><function>sd_bus_error_set()</function> will return an <varname>errno</varname>-like value (see
178    <citerefentry
179    project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
180    determined from the specified error name <parameter>name</parameter>. If <parameter>name</parameter> is
181    <constant>NULL</constant>, it is assumed that no error occurred, and <constant>0</constant> is returned.
182    If <parameter>name</parameter> is nonnull, a negative value is always returned. If
183    <parameter>e</parameter> is <constant>NULL</constant>, no error structure is initialized, but
184    <parameter>name</parameter> is still converted into an <varname>errno</varname>-style value.</para>
185
186    <para>Various well-known D-Bus errors are converted to well-known <varname>errno</varname> counterparts,
187    and the other ones to <constant>-EIO</constant>. See
188    <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry> for a
189    list of well-known error names. Additional error mappings may be defined with
190    <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
191    </para>
192
193    <para><function>sd_bus_error_set()</function> is designed to be conveniently used in a
194    <function>return</function> statement. If <parameter>message</parameter> is <constant>NULL</constant>, no
195    message is set. This call can fail if no memory may be allocated for the name and message strings, in
196    which case an <constant>SD_BUS_ERROR_NO_MEMORY</constant> error will be set instead and
197    <constant>-ENOMEM</constant> returned. </para>
198
199    <para><function>sd_bus_error_setf()</function> is similar to
200    <function>sd_bus_error_set()</function>, but takes a <citerefentry
201    project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
202    format string and corresponding arguments to generate the
203    <structfield>message</structfield> field.</para>
204
205    <para><function>sd_bus_error_set_const()</function> is similar to
206    <function>sd_bus_error_set()</function>, but the string parameters are not copied internally, and must
207    hence remain constant and valid for the lifetime of <parameter>e</parameter>. Use this call to avoid
208    memory allocations when setting error structures. Since this call does not allocate memory, it will not
209    fail with an out-of-memory condition as <function>sd_bus_error_set()</function> may, as described
210    above. Alternatively, the <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used to generate a
211    literal, constant bus error structure on-the-fly.</para>
212
213    <para><function>sd_bus_error_set_errno()</function> will immediately return <constant>0</constant> if the
214    specified error parameter <parameter>error</parameter> is <constant>0</constant>. Otherwise, it will set
215    <structfield>name</structfield> from an <varname>errno</varname>-like value that is converted to a D-Bus
216    error. <citerefentry
217    project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> will
218    be used to set <structfield>message</structfield>. Well-known D-Bus error names will be used for
219    <structfield>name</structfield> if applicable, otherwise a name in the <literal>System.Error.</literal>
220    namespace will be generated. The sign of the specified error number is ignored and the absolute value is
221    used implicitly. If the specified error <parameter>error</parameter> is non-zero, the call always returns
222    a negative value, for convenient usage in <function>return</function> statements. This call might fail
223    due to lack of memory, in which case an <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead,
224    and <constant>-ENOMEM</constant> is returned.</para>
225
226    <para><function>sd_bus_error_set_errnof()</function> is similar to
227    <function>sd_bus_error_set_errno()</function>, but in addition to
228    <parameter>error</parameter>, takes a <citerefentry
229    project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
230    format string and corresponding arguments.  The
231    <structfield>message</structfield> field will be generated from
232    <parameter>format</parameter> and the arguments.</para>
233
234    <para><function>sd_bus_error_set_errnofv()</function> is similar to
235    <function>sd_bus_error_set_errnof()</function>, but takes the
236    format string parameters as <citerefentry
237    project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
238    parameter list.</para>
239
240    <para><function>sd_bus_error_get_errno()</function> converts the <structfield>name</structfield> field of
241    an error structure to an <varname>errno</varname>-like (positive) value using the same rules as
242    <function>sd_bus_error_set()</function>.  If <parameter>e</parameter> is <constant>NULL</constant>,
243    <constant>0</constant> will be returned.</para>
244
245    <para><function>sd_bus_error_copy()</function> will initialize <parameter>dst</parameter> using the
246    values in <parameter>e</parameter>, if <parameter>e</parameter> has been set with an error value before.
247    Otherwise, it will return immediately. If the strings in <parameter>e</parameter> were set using
248    <function>sd_bus_error_set_const()</function>, they will be shared. Otherwise, they will be
249    copied. Returns a converted <varname>errno</varname>-like, negative error code or <constant>0</constant>.
250    Before this call, <parameter>dst</parameter> must be unset, i.e. either freshly initialized with
251    <constant>NULL</constant> or reset using <function>sd_bus_error_free()</function>.</para>
252
253    <para><function>sd_bus_error_move()</function> is similar to <function>sd_bus_error_copy()</function>,
254    but will move any error information from <parameter>e</parameter> into <parameter>dst</parameter>,
255    resetting the former. This function cannot fail, as no new memory is allocated. Note that if
256    <parameter>e</parameter> is not set, <parameter>dst</parameter> is initialized to
257    <constant>SD_BUS_ERROR_NULL</constant>. Moreover, if <parameter>dst</parameter> is
258    <constant>NULL</constant> no operation is executed on it and resources held by <parameter>e</parameter>
259    are freed and reset. Returns a converted <varname>errno</varname>-like, non-positive error value.</para>
260
261    <para><function>sd_bus_error_is_set()</function> will return a
262    non-zero value if <parameter>e</parameter> is
263    non-<constant>NULL</constant> and an error has been set,
264    <constant>false</constant> otherwise.</para>
265
266    <para><function>sd_bus_error_has_name()</function> will return a
267    non-zero value if <parameter>e</parameter> is
268    non-<constant>NULL</constant> and an error with the same
269    <parameter>name</parameter> has been set,
270    <constant>false</constant> otherwise.</para>
271
272    <para><function>sd_bus_error_has_names_sentinel()</function> is similar to
273    <function>sd_bus_error_has_name()</function>, but takes multiple names to check against. The list must be
274    terminated with <constant>NULL</constant>. <function>sd_bus_error_has_names()</function>
275    is a macro wrapper around <function>sd_bus_error_has_names_sentinel()</function> that adds the
276    <constant>NULL</constant> sentinel automatically.</para>
277
278    <para><function>sd_bus_error_free()</function> will destroy
279    resources held by <parameter>e</parameter>. The parameter itself
280    will not be deallocated, and must be <citerefentry
281    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
282    by the caller if necessary. The function may also be called safely
283    on unset errors (error structures with both fields set to <constant>NULL</constant>),
284    in which case it performs no operation. This call will reset the
285    error structure after freeing the data, so that all fields are set
286    to <constant>NULL</constant>. The structure may be reused afterwards.</para>
287  </refsect1>
288
289  <refsect1>
290    <title>Return Value</title>
291
292    <para>The functions <function>sd_bus_error_set()</function>, <function>sd_bus_error_setf()</function>,
293    and <function>sd_bus_error_set_const()</function> always return <constant>0</constant> when the specified
294    error value is <constant>NULL</constant>, and a negative errno-like value corresponding to the
295    <parameter>name</parameter> parameter otherwise. The functions
296    <function>sd_bus_error_set_errno()</function>, <function>sd_bus_error_set_errnof()</function> and
297    <function>sd_bus_error_set_errnofv()</function>, return <constant>0</constant> when the specified error
298    value is <constant>0</constant>, and a negative errno-like value corresponding to the
299    <parameter>error</parameter> parameter otherwise. If an error occurs internally, one of the negative
300    error values listed below will be returned.</para>
301
302    <para><function>sd_bus_error_get_errno()</function> returns
303    <constant>false</constant> when <parameter>e</parameter> is
304    <constant>NULL</constant>, and a positive errno value mapped from
305    <parameter>e-&gt;name</parameter> otherwise.</para>
306
307    <para><function>sd_bus_error_copy()</function> and <function>sd_bus_error_move()</function> return a
308    negative error value converted from the source error, and zero if the error has not been set.</para>
309
310    <para><function>sd_bus_error_is_set()</function> returns a
311    non-zero value when <parameter>e</parameter> and the
312    <structfield>name</structfield> field are
313    non-<constant>NULL</constant>, zero otherwise.</para>
314
315    <para><function>sd_bus_error_has_name()</function>, <function>sd_bus_error_has_names()</function>, and
316    <function>sd_bus_error_has_names_sentinel()</function> return a non-zero value when <parameter>e</parameter> is
317    non-<constant>NULL</constant> and the <structfield>name</structfield> field is equal to one of the given
318    names, zero otherwise.</para>
319  </refsect1>
320
321  <refsect1>
322    <title>Reference ownership</title>
323    <para><structname>sd_bus_error</structname> is not reference
324    counted. Users should destroy resources held by it by calling
325    <function>sd_bus_error_free()</function>. Usually, error structures
326    are allocated on the stack or passed in as function parameters,
327    but they may also be allocated dynamically, in which case it is
328    the duty of the caller to <citerefentry
329    project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
330    the memory held by the structure itself after freeing its contents
331    with <function>sd_bus_error_free()</function>.</para>
332
333    <refsect2>
334      <title>Errors</title>
335
336      <para>Returned errors may indicate the following problems:</para>
337
338      <variablelist>
339
340        <varlistentry>
341          <term><constant>-EINVAL</constant></term>
342
343          <listitem><para>Error was already set in <structname>sd_bus_error</structname> structure when one
344          the error-setting functions was called.</para></listitem>
345        </varlistentry>
346
347        <varlistentry>
348          <term><constant>-ENOMEM</constant></term>
349
350          <listitem><para>Memory allocation failed.</para></listitem>
351        </varlistentry>
352      </variablelist>
353    </refsect2>
354  </refsect1>
355
356  <xi:include href="libsystemd-pkgconfig.xml" />
357
358  <refsect1>
359    <title>See Also</title>
360
361    <para>
362      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
363      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
364      <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
365      <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
366      <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
367      <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
368    </para>
369  </refsect1>
370
371</refentry>
372