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+
8 Copyright © 2014 Zbigniew Jędrzejewski-Szmek
11 <refentry id="sd_bus_error" xmlns:xi="http://www.w3.org/2001/XInclude">
14 <title>sd_bus_error</title>
15 <productname>systemd</productname>
19 <refentrytitle>sd_bus_error</refentrytitle>
20 <manvolnum>3</manvolnum>
24 <refname>sd_bus_error</refname>
25 <refname>SD_BUS_ERROR_MAKE_CONST</refname>
26 <refname>SD_BUS_ERROR_NULL</refname>
27 <refname>sd_bus_error_free</refname>
28 <refname>sd_bus_error_set</refname>
29 <refname>sd_bus_error_setf</refname>
30 <refname>sd_bus_error_set_const</refname>
31 <refname>sd_bus_error_set_errno</refname>
32 <refname>sd_bus_error_set_errnof</refname>
33 <refname>sd_bus_error_set_errnofv</refname>
34 <refname>sd_bus_error_get_errno</refname>
35 <refname>sd_bus_error_copy</refname>
36 <refname>sd_bus_error_is_set</refname>
37 <refname>sd_bus_error_has_name</refname>
39 <refpurpose>sd-bus error handling</refpurpose>
44 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
46 <funcsynopsisinfo>typedef struct {
50 } 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>
60 <funcdef>void <function>sd_bus_error_free</function></funcdef>
61 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
65 <funcdef>int <function>sd_bus_error_set</function></funcdef>
66 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
67 <paramdef>const char *<parameter>name</parameter></paramdef>
68 <paramdef>const char *<parameter>message</parameter></paramdef>
72 <funcdef>int <function>sd_bus_error_setf</function></funcdef>
73 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
74 <paramdef>const char *<parameter>name</parameter></paramdef>
75 <paramdef>const char *<parameter>format</parameter></paramdef>
76 <paramdef>…</paramdef>
80 <funcdef>int <function>sd_bus_error_set_const</function></funcdef>
81 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
82 <paramdef>const char *<parameter>name</parameter></paramdef>
83 <paramdef>const char *<parameter>message</parameter></paramdef>
87 <funcdef>int <function>sd_bus_error_set_errno</function></funcdef>
88 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
89 <paramdef>int <parameter>error</parameter></paramdef>
93 <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef>
94 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
95 <paramdef>int <parameter>error</parameter></paramdef>
96 <paramdef>const char *<parameter>format</parameter></paramdef>
97 <paramdef>…</paramdef>
101 <funcdef>int <function>sd_bus_error_set_errnofv</function></funcdef>
102 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
103 <paramdef>int <parameter>error</parameter></paramdef>
104 <paramdef>const char *<parameter>format</parameter></paramdef>
105 <paramdef>va_list ap</paramdef>
109 <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
110 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
114 <funcdef>int <function>sd_bus_error_copy</function></funcdef>
115 <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef>
116 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
120 <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
121 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
125 <funcdef>int <function>sd_bus_error_has_name</function></funcdef>
126 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
127 <paramdef>const char *<parameter>name</parameter></paramdef>
134 <title>Description</title>
136 <para>The <structname>sd_bus_error</structname> structure carries
137 information about a D-Bus error condition. The functions described
138 below may be used to set and query fields in this structure. The
139 <structfield>name</structfield> field contains a short identifier
140 of an error. It should follow the rules for error names described
141 in the D-Bus specification, subsection <ulink
142 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
143 Names</ulink>. A number of common, standardized error names are
145 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
146 but additional domain-specific errors may be defined by
147 applications. The <structfield>message</structfield> field usually
148 contains a human-readable string describing the details, but might
149 be NULL. An unset <structname>sd_bus_error</structname> structure
150 should have both fields initialized to NULL. Set an error
151 structure to <constant>SD_BUS_ERROR_NULL</constant> in order to
152 reset both fields to NULL. When no longer necessary, resources
153 held by the <structname>sd_bus_error</structname>structure should
154 be destroyed with <function>sd_bus_error_free()</function>.</para>
156 <para><function>sd_bus_error_set()</function> sets an error
157 structure to the specified name and message strings. The strings
158 will be copied into internal, newly allocated memory. It is
159 essential to free the error structure again when it is not
160 required anymore (see above). The function will return an
161 <varname>errno</varname>-like negative value (see <citerefentry
162 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
163 determined from the specified error name. Various well-known
164 D-Bus errors are converted to well-known <varname>errno</varname>
165 counterparts, and the other ones to <constant>-EIO</constant>. See
166 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>
167 for a list of well-known error names. Additional error mappings
169 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
170 <parameter>e</parameter> is NULL, no error structure is initialized,
171 but the error is still converted into an
172 <varname>errno</varname>-style error. If
173 <parameter>name</parameter> is <constant>NULL</constant>, it is
174 assumed that no error occurred, and 0 is returned. This means that
175 this function may be conveniently used in a
176 <function>return</function> statement. If
177 <parameter>message</parameter> is NULL, no message is set. This
178 call can fail if no memory may be allocated for the name and
179 message strings, in which case an
180 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set
181 instead and -ENOMEM be returned. Do not use this call on error
182 structures that are already initialized. If you intend to reuse an
183 error structure, free the old data stored in it with
184 <function>sd_bus_error_free()</function> first.</para>
186 <para><function>sd_bus_error_setf()</function> is similar to
187 <function>sd_bus_error_set()</function>, but takes a <citerefentry
188 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
189 format string and corresponding arguments to generate the
190 <structfield>message</structfield> field.</para>
192 <para><function>sd_bus_error_set_const()</function> is similar to
193 <function>sd_bus_error_set()</function>, but the string parameters
194 are not copied internally, and must hence remain constant and
195 valid for the lifetime of <parameter>e</parameter>. Use this call
196 to avoid memory allocations when setting error structures. Since
197 this call does not allocate memory, it will not fail with an
198 out-of-memory condition as
199 <function>sd_bus_error_set()</function> can, as described
200 above. Alternatively, the
201 <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used
202 to generate a literal, constant bus error structure
205 <para><function>sd_bus_error_set_errno()</function> will set
206 <structfield>name</structfield> from an
207 <varname>errno</varname>-like value that is converted to a D-Bus
209 project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
210 will be used to set <structfield>message</structfield>. Well-known
211 D-Bus error names will be used for <structfield>name</structfield>
212 if applicable, otherwise a name in the
213 <literal>System.Error.</literal> namespace will be generated. The
214 sign of the specified error number is ignored. The absolute value
215 is used implicitly. The call always returns a negative value, for
216 convenient usage in <function>return</function> statements. This
217 call might fail due to lack of memory, in which case an
218 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead,
219 and -ENOMEM is returned.</para>
221 <para><function>sd_bus_error_set_errnof()</function> is similar to
222 <function>sd_bus_error_set_errno()</function>, but in addition to
223 <parameter>error</parameter>, takes a <citerefentry
224 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
225 format string and corresponding arguments. The
226 <structfield>message</structfield> field will be generated from
227 <parameter>format</parameter> and the arguments.</para>
229 <para><function>sd_bus_error_set_errnofv()</function> is similar to
230 <function>sd_bus_error_set_errnof()</function>, but takes the
231 format string parameters as <citerefentry
232 project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
233 parameter list.</para>
235 <para><function>sd_bus_error_get_errno()</function> converts the
236 <structfield>name</structfield> field of an error structure to an
237 <varname>errno</varname>-like (positive) value using the same
238 rules as <function>sd_bus_error_set()</function>. If
239 <parameter>e</parameter> is <constant>NULL</constant>, 0 will be
242 <para><function>sd_bus_error_copy()</function> will initialize
243 <parameter>dst</parameter> using the values in
244 <parameter>e</parameter>. If the strings in
245 <parameter>e</parameter> were set using
246 <function>sd_bus_error_set_const()</function>, they will be shared.
247 Otherwise, they will be copied. Returns a converted
248 <varname>errno</varname>-like, negative error code.</para>
250 <para><function>sd_bus_error_is_set()</function> will return a
251 non-zero value if <parameter>e</parameter> is
252 non-<constant>NULL</constant> and an error has been set,
253 <constant>false</constant> otherwise.</para>
255 <para><function>sd_bus_error_has_name()</function> will return a
256 non-zero value if <parameter>e</parameter> is
257 non-<constant>NULL</constant> and an error with the same
258 <parameter>name</parameter> has been set,
259 <constant>false</constant> otherwise.</para>
261 <para><function>sd_bus_error_free()</function> will destroy
262 resources held by <parameter>e</parameter>. The parameter itself
263 will not be deallocated, and must be <citerefentry
264 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
265 by the caller if necessary. The function may also be called safely
266 on unset errors (error structures with both fields set to NULL),
267 in which case it performs no operation. This call will reset the
268 error structure after freeing the data, so that all fields are set
269 to NULL. The structure may be reused afterwards.</para>
273 <title>Return Value</title>
275 <para>The functions <function>sd_bus_error_set()</function>,
276 <function>sd_bus_error_setf()</function>, and
277 <function>sd_bus_error_set_const()</function>, when successful,
278 return the negative errno value corresponding to the
279 <parameter>name</parameter> parameter. The functions
280 <function>sd_bus_error_set_errno()</function>,
281 <function>sd_bus_error_set_errnof()</function> and
282 <function>sd_bus_error_set_errnofv()</function>, when successful,
283 return the negative value of the <parameter>error</parameter>
284 parameter. If an error occurs, one of the negative error values
285 listed below will be returned.</para>
287 <para><function>sd_bus_error_get_errno()</function> returns
288 <constant>false</constant> when <parameter>e</parameter> is
289 <constant>NULL</constant>, and a positive errno value mapped from
290 <parameter>e->name</parameter> otherwise.</para>
292 <para><function>sd_bus_error_copy()</function> returns 0 or a
293 positive integer on success, and a negative error value converted
294 from the error name otherwise.</para>
296 <para><function>sd_bus_error_is_set()</function> returns a
297 non-zero value when <parameter>e</parameter> and the
298 <structfield>name</structfield> field are
299 non-<constant>NULL</constant>, zero otherwise.</para>
301 <para><function>sd_bus_error_has_name()</function> returns a
302 non-zero value when <parameter>e</parameter> is
303 non-<constant>NULL</constant> and the
304 <structfield>name</structfield> field is equal to
305 <parameter>name</parameter>, zero otherwise.</para>
309 <title>Reference ownership</title>
310 <para><structname>sd_bus_error</structname> is not reference
311 counted. Users should destroy resources held by it by calling
312 <function>sd_bus_error_free()</function>. Usually, error structures
313 are allocated on the stack or passed in as function parameters,
314 but they may also be allocated dynamically, in which case it is
315 the duty of the caller to <citerefentry
316 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
317 the memory held by the structure itself after freeing its contents
318 with <function>sd_bus_error_free()</function>.</para>
322 <title>Errors</title>
324 <para>Returned errors may indicate the following problems:</para>
329 <term><constant>-EINVAL</constant></term>
331 <listitem><para>Error was already set in
332 <structname>sd_bus_error</structname> structure when one the
333 error-setting functions was called.</para></listitem>
337 <term><constant>-ENOMEM</constant></term>
339 <listitem><para>Memory allocation failed.</para></listitem>
344 <xi:include href="libelogind-pkgconfig.xml" />
347 <title>See Also</title>
350 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
351 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
352 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
353 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
354 <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
355 <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>