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 <contrib>A monkey with a typewriter</contrib>
20 <firstname>Zbigniew</firstname>
21 <surname>Jędrzejewski-Szmek</surname>
22 <email>zbyszek@in.waw.pl</email>
28 <refentrytitle>sd_bus_error</refentrytitle>
29 <manvolnum>3</manvolnum>
33 <refname>sd_bus_error</refname>
34 <refname>SD_BUS_ERROR_MAKE_CONST</refname>
35 <refname>SD_BUS_ERROR_NULL</refname>
36 <refname>sd_bus_error_free</refname>
37 <refname>sd_bus_error_set</refname>
38 <refname>sd_bus_error_setf</refname>
39 <refname>sd_bus_error_set_const</refname>
40 <refname>sd_bus_error_set_errno</refname>
41 <refname>sd_bus_error_set_errnof</refname>
42 <refname>sd_bus_error_set_errnofv</refname>
43 <refname>sd_bus_error_get_errno</refname>
44 <refname>sd_bus_error_copy</refname>
45 <refname>sd_bus_error_is_set</refname>
46 <refname>sd_bus_error_has_name</refname>
48 <refpurpose>sd-bus error handling</refpurpose>
53 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
55 <funcsynopsisinfo>typedef struct {
59 } sd_bus_error;</funcsynopsisinfo>
62 <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant>
65 <constant>SD_BUS_ERROR_NULL</constant>
69 <funcdef>void <function>sd_bus_error_free</function></funcdef>
70 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
74 <funcdef>int <function>sd_bus_error_set</function></funcdef>
75 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
76 <paramdef>const char *<parameter>name</parameter></paramdef>
77 <paramdef>const char *<parameter>message</parameter></paramdef>
81 <funcdef>int <function>sd_bus_error_setf</function></funcdef>
82 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
83 <paramdef>const char *<parameter>name</parameter></paramdef>
84 <paramdef>const char *<parameter>format</parameter></paramdef>
85 <paramdef>…</paramdef>
89 <funcdef>int <function>sd_bus_error_set_const</function></funcdef>
90 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
91 <paramdef>const char *<parameter>name</parameter></paramdef>
92 <paramdef>const char *<parameter>message</parameter></paramdef>
96 <funcdef>int <function>sd_bus_error_set_errno</function></funcdef>
97 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
98 <paramdef>int <parameter>error</parameter></paramdef>
102 <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef>
103 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
104 <paramdef>int <parameter>error</parameter></paramdef>
105 <paramdef>const char *<parameter>format</parameter></paramdef>
106 <paramdef>…</paramdef>
110 <funcdef>int <function>sd_bus_error_set_errnofv</function></funcdef>
111 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
112 <paramdef>int <parameter>error</parameter></paramdef>
113 <paramdef>const char *<parameter>format</parameter></paramdef>
114 <paramdef>va_list ap</paramdef>
118 <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
119 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
123 <funcdef>int <function>sd_bus_error_copy</function></funcdef>
124 <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef>
125 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
129 <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
130 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
134 <funcdef>int <function>sd_bus_error_has_name</function></funcdef>
135 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
136 <paramdef>const char *<parameter>name</parameter></paramdef>
143 <title>Description</title>
145 <para>The <structname>sd_bus_error</structname> structure carries
146 information about a D-Bus error condition. The functions described
147 below may be used to set and query fields in this structure. The
148 <structfield>name</structfield> field contains a short identifier
149 of an error. It should follow the rules for error names described
150 in the D-Bus specification, subsection <ulink
151 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
152 Names</ulink>. A number of common, standardized error names are
154 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
155 but additional domain-specific errors may be defined by
156 applications. The <structfield>message</structfield> field usually
157 contains a human-readable string describing the details, but might
158 be NULL. An unset <structname>sd_bus_error</structname> structure
159 should have both fields initialized to NULL. Set an error
160 structure to <constant>SD_BUS_ERROR_NULL</constant> in order to
161 reset both fields to NULL. When no longer necessary, resources
162 held by the <structname>sd_bus_error</structname>structure should
163 be destroyed with <function>sd_bus_error_free()</function>.</para>
165 <para><function>sd_bus_error_set()</function> sets an error
166 structure to the specified name and message strings. The strings
167 will be copied into internal, newly allocated memory. It is
168 essential to free the error structure again when it is not
169 required anymore (see above). The function will return an
170 <varname>errno</varname>-like negative value (see <citerefentry
171 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
172 determined from the specified error name. Various well-known
173 D-Bus errors are converted to well-known <varname>errno</varname>
174 counterparts, and the other ones to <constant>-EIO</constant>. See
175 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>
176 for a list of well-known error names. Additional error mappings
178 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
179 <parameter>e</parameter> is NULL, no error structure is initialized,
180 but the error is still converted into an
181 <varname>errno</varname>-style error. If
182 <parameter>name</parameter> is <constant>NULL</constant>, it is
183 assumed that no error occurred, and 0 is returned. This means that
184 this function may be conveniently used in a
185 <function>return</function> statement. If
186 <parameter>message</parameter> is NULL, no message is set. This
187 call can fail if no memory may be allocated for the name and
188 message strings, in which case an
189 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set
190 instead and -ENOMEM be returned. Do not use this call on error
191 structures that are already initialized. If you intend to reuse an
192 error structure, free the old data stored in it with
193 <function>sd_bus_error_free()</function> first.</para>
195 <para><function>sd_bus_error_setf()</function> is similar to
196 <function>sd_bus_error_set()</function>, but takes a <citerefentry
197 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
198 format string and corresponding arguments to generate the
199 <structfield>message</structfield> field.</para>
201 <para><function>sd_bus_error_set_const()</function> is similar to
202 <function>sd_bus_error_set()</function>, but the string parameters
203 are not copied internally, and must hence remain constant and
204 valid for the lifetime of <parameter>e</parameter>. Use this call
205 to avoid memory allocations when setting error structures. Since
206 this call does not allocate memory, it will not fail with an
207 out-of-memory condition as
208 <function>sd_bus_error_set()</function> can, as described
209 above. Alternatively, the
210 <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used
211 to generate a literal, constant bus error structure
214 <para><function>sd_bus_error_set_errno()</function> will set
215 <structfield>name</structfield> from an
216 <varname>errno</varname>-like value that is converted to a D-Bus
218 project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
219 will be used to set <structfield>message</structfield>. Well-known
220 D-Bus error names will be used for <structfield>name</structfield>
221 if applicable, otherwise a name in the
222 <literal>System.Error.</literal> namespace will be generated. The
223 sign of the specified error number is ignored. The absolute value
224 is used implicitly. The call always returns a negative value, for
225 convenient usage in <function>return</function> statements. This
226 call might fail due to lack of memory, in which case an
227 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead,
228 and -ENOMEM is returned.</para>
230 <para><function>sd_bus_error_set_errnof()</function> is similar to
231 <function>sd_bus_error_set_errno()</function>, but in addition to
232 <parameter>error</parameter>, takes a <citerefentry
233 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
234 format string and corresponding arguments. The
235 <structfield>message</structfield> field will be generated from
236 <parameter>format</parameter> and the arguments.</para>
238 <para><function>sd_bus_error_set_errnofv()</function> is similar to
239 <function>sd_bus_error_set_errnof()</function>, but takes the
240 format string parameters as <citerefentry
241 project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
242 parameter list.</para>
244 <para><function>sd_bus_error_get_errno()</function> converts the
245 <structfield>name</structfield> field of an error structure to an
246 <varname>errno</varname>-like (positive) value using the same
247 rules as <function>sd_bus_error_set()</function>. If
248 <parameter>e</parameter> is <constant>NULL</constant>, 0 will be
251 <para><function>sd_bus_error_copy()</function> will initialize
252 <parameter>dst</parameter> using the values in
253 <parameter>e</parameter>. If the strings in
254 <parameter>e</parameter> were set using
255 <function>sd_bus_error_set_const()</function>, they will be shared.
256 Otherwise, they will be copied. Returns a converted
257 <varname>errno</varname>-like, negative error code.</para>
259 <para><function>sd_bus_error_is_set()</function> will return a
260 non-zero value if <parameter>e</parameter> is
261 non-<constant>NULL</constant> and an error has been set,
262 <constant>false</constant> otherwise.</para>
264 <para><function>sd_bus_error_has_name()</function> will return a
265 non-zero value if <parameter>e</parameter> is
266 non-<constant>NULL</constant> and an error with the same
267 <parameter>name</parameter> has been set,
268 <constant>false</constant> otherwise.</para>
270 <para><function>sd_bus_error_free()</function> will destroy
271 resources held by <parameter>e</parameter>. The parameter itself
272 will not be deallocated, and must be <citerefentry
273 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
274 by the caller if necessary. The function may also be called safely
275 on unset errors (error structures with both fields set to NULL),
276 in which case it performs no operation. This call will reset the
277 error structure after freeing the data, so that all fields are set
278 to NULL. The structure may be reused afterwards.</para>
282 <title>Return Value</title>
284 <para>The functions <function>sd_bus_error_set()</function>,
285 <function>sd_bus_error_setf()</function>, and
286 <function>sd_bus_error_set_const()</function>, when successful,
287 return the negative errno value corresponding to the
288 <parameter>name</parameter> parameter. The functions
289 <function>sd_bus_error_set_errno()</function>,
290 <function>sd_bus_error_set_errnof()</function> and
291 <function>sd_bus_error_set_errnofv()</function>, when successful,
292 return the negative value of the <parameter>error</parameter>
293 parameter. If an error occurs, one of the negative error values
294 listed below will be returned.</para>
296 <para><function>sd_bus_error_get_errno()</function> returns
297 <constant>false</constant> when <parameter>e</parameter> is
298 <constant>NULL</constant>, and a positive errno value mapped from
299 <parameter>e->name</parameter> otherwise.</para>
301 <para><function>sd_bus_error_copy()</function> returns 0 or a
302 positive integer on success, and a negative error value converted
303 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>
331 <title>Errors</title>
333 <para>Returned errors may indicate the following problems:</para>
338 <term><constant>-EINVAL</constant></term>
340 <listitem><para>Error was already set in
341 <structname>sd_bus_error</structname> structure when one the
342 error-setting functions was called.</para></listitem>
346 <term><constant>-ENOMEM</constant></term>
348 <listitem><para>Memory allocation failed.</para></listitem>
353 <xi:include href="libelogind-pkgconfig.xml" />
356 <title>See Also</title>
359 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
360 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
361 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
362 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
363 <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
364 <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>