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 This file is part of systemd.
10 Copyright 2014 Zbigniew Jędrzejewski-Szmek
13 <refentry id="sd_bus_error" xmlns:xi="http://www.w3.org/2001/XInclude">
16 <title>sd_bus_error</title>
17 <productname>systemd</productname>
21 <contrib>A monkey with a typewriter</contrib>
22 <firstname>Zbigniew</firstname>
23 <surname>Jędrzejewski-Szmek</surname>
24 <email>zbyszek@in.waw.pl</email>
30 <refentrytitle>sd_bus_error</refentrytitle>
31 <manvolnum>3</manvolnum>
35 <refname>sd_bus_error</refname>
36 <refname>SD_BUS_ERROR_MAKE_CONST</refname>
37 <refname>SD_BUS_ERROR_NULL</refname>
38 <refname>sd_bus_error_free</refname>
39 <refname>sd_bus_error_set</refname>
40 <refname>sd_bus_error_setf</refname>
41 <refname>sd_bus_error_set_const</refname>
42 <refname>sd_bus_error_set_errno</refname>
43 <refname>sd_bus_error_set_errnof</refname>
44 <refname>sd_bus_error_set_errnofv</refname>
45 <refname>sd_bus_error_get_errno</refname>
46 <refname>sd_bus_error_copy</refname>
47 <refname>sd_bus_error_is_set</refname>
48 <refname>sd_bus_error_has_name</refname>
50 <refpurpose>sd-bus error handling</refpurpose>
55 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
57 <funcsynopsisinfo>typedef struct {
61 } sd_bus_error;</funcsynopsisinfo>
64 <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant>
67 <constant>SD_BUS_ERROR_NULL</constant>
71 <funcdef>void <function>sd_bus_error_free</function></funcdef>
72 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
76 <funcdef>int <function>sd_bus_error_set</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_setf</function></funcdef>
84 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
85 <paramdef>const char *<parameter>name</parameter></paramdef>
86 <paramdef>const char *<parameter>format</parameter></paramdef>
87 <paramdef>…</paramdef>
91 <funcdef>int <function>sd_bus_error_set_const</function></funcdef>
92 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
93 <paramdef>const char *<parameter>name</parameter></paramdef>
94 <paramdef>const char *<parameter>message</parameter></paramdef>
98 <funcdef>int <function>sd_bus_error_set_errno</function></funcdef>
99 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
100 <paramdef>int <parameter>error</parameter></paramdef>
104 <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef>
105 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
106 <paramdef>int <parameter>error</parameter></paramdef>
107 <paramdef>const char *<parameter>format</parameter></paramdef>
108 <paramdef>…</paramdef>
112 <funcdef>int <function>sd_bus_error_set_errnofv</function></funcdef>
113 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
114 <paramdef>int <parameter>error</parameter></paramdef>
115 <paramdef>const char *<parameter>format</parameter></paramdef>
116 <paramdef>va_list ap</paramdef>
120 <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
121 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
125 <funcdef>int <function>sd_bus_error_copy</function></funcdef>
126 <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef>
127 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
131 <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
132 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
136 <funcdef>int <function>sd_bus_error_has_name</function></funcdef>
137 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
138 <paramdef>const char *<parameter>name</parameter></paramdef>
145 <title>Description</title>
147 <para>The <structname>sd_bus_error</structname> structure carries
148 information about a D-Bus error condition. The functions described
149 below may be used to set and query fields in this structure. The
150 <structfield>name</structfield> field contains a short identifier
151 of an error. It should follow the rules for error names described
152 in the D-Bus specification, subsection <ulink
153 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
154 Names</ulink>. A number of common, standardized error names are
156 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
157 but additional domain-specific errors may be defined by
158 applications. The <structfield>message</structfield> field usually
159 contains a human-readable string describing the details, but might
160 be NULL. An unset <structname>sd_bus_error</structname> structure
161 should have both fields initialized to NULL. Set an error
162 structure to <constant>SD_BUS_ERROR_NULL</constant> in order to
163 reset both fields to NULL. When no longer necessary, resources
164 held by the <structname>sd_bus_error</structname>structure should
165 be destroyed with <function>sd_bus_error_free()</function>.</para>
167 <para><function>sd_bus_error_set()</function> sets an error
168 structure to the specified name and message strings. The strings
169 will be copied into internal, newly allocated memory. It is
170 essential to free the error structure again when it is not
171 required anymore (see above). The function will return an
172 <varname>errno</varname>-like negative value (see <citerefentry
173 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
174 determined from the specified error name. Various well-known
175 D-Bus errors are converted to well-known <varname>errno</varname>
176 counterparts, and the other ones to <constant>-EIO</constant>. See
177 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>
178 for a list of well-known error names. Additional error mappings
180 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
181 <parameter>e</parameter> is NULL, no error structure is initialized,
182 but the error is still converted into an
183 <varname>errno</varname>-style error. If
184 <parameter>name</parameter> is <constant>NULL</constant>, it is
185 assumed that no error occurred, and 0 is returned. This means that
186 this function may be conveniently used in a
187 <function>return</function> statement. If
188 <parameter>message</parameter> is NULL, no message is set. This
189 call can fail if no memory may be allocated for the name and
190 message strings, in which case an
191 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set
192 instead and -ENOMEM be returned. Do not use this call on error
193 structures that are already initialized. If you intend to reuse an
194 error structure, free the old data stored in it with
195 <function>sd_bus_error_free()</function> first.</para>
197 <para><function>sd_bus_error_setf()</function> is similar to
198 <function>sd_bus_error_set()</function>, but takes a <citerefentry
199 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
200 format string and corresponding arguments to generate the
201 <structfield>message</structfield> field.</para>
203 <para><function>sd_bus_error_set_const()</function> is similar to
204 <function>sd_bus_error_set()</function>, but the string parameters
205 are not copied internally, and must hence remain constant and
206 valid for the lifetime of <parameter>e</parameter>. Use this call
207 to avoid memory allocations when setting error structures. Since
208 this call does not allocate memory, it will not fail with an
209 out-of-memory condition as
210 <function>sd_bus_error_set()</function> can, as described
211 above. Alternatively, the
212 <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used
213 to generate a literal, constant bus error structure
216 <para><function>sd_bus_error_set_errno()</function> will set
217 <structfield>name</structfield> from an
218 <varname>errno</varname>-like value that is converted to a D-Bus
220 project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
221 will be used to set <structfield>message</structfield>. Well-known
222 D-Bus error names will be used for <structfield>name</structfield>
223 if applicable, otherwise a name in the
224 <literal>System.Error.</literal> namespace will be generated. The
225 sign of the specified error number is ignored. The absolute value
226 is used implicitly. The call always returns a negative value, for
227 convenient usage in <function>return</function> statements. This
228 call might fail due to lack of memory, in which case an
229 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead,
230 and -ENOMEM is returned.</para>
232 <para><function>sd_bus_error_set_errnof()</function> is similar to
233 <function>sd_bus_error_set_errno()</function>, but in addition to
234 <parameter>error</parameter>, takes a <citerefentry
235 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
236 format string and corresponding arguments. The
237 <structfield>message</structfield> field will be generated from
238 <parameter>format</parameter> and the arguments.</para>
240 <para><function>sd_bus_error_set_errnofv()</function> is similar to
241 <function>sd_bus_error_set_errnof()</function>, but takes the
242 format string parameters as <citerefentry
243 project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
244 parameter list.</para>
246 <para><function>sd_bus_error_get_errno()</function> converts the
247 <structfield>name</structfield> field of an error structure to an
248 <varname>errno</varname>-like (positive) value using the same
249 rules as <function>sd_bus_error_set()</function>. If
250 <parameter>e</parameter> is <constant>NULL</constant>, 0 will be
253 <para><function>sd_bus_error_copy()</function> will initialize
254 <parameter>dst</parameter> using the values in
255 <parameter>e</parameter>. If the strings in
256 <parameter>e</parameter> were set using
257 <function>sd_bus_error_set_const()</function>, they will be shared.
258 Otherwise, they will be copied. Returns a converted
259 <varname>errno</varname>-like, negative error code.</para>
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>
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>
272 <para><function>sd_bus_error_free()</function> will destroy
273 resources held by <parameter>e</parameter>. The parameter itself
274 will not be deallocated, and must be <citerefentry
275 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
276 by the caller if necessary. The function may also be called safely
277 on unset errors (error structures with both fields set to NULL),
278 in which case it performs no operation. This call will reset the
279 error structure after freeing the data, so that all fields are set
280 to NULL. The structure may be reused afterwards.</para>
284 <title>Return Value</title>
286 <para>The functions <function>sd_bus_error_set()</function>,
287 <function>sd_bus_error_setf()</function>, and
288 <function>sd_bus_error_set_const()</function>, when successful,
289 return the negative errno value corresponding to the
290 <parameter>name</parameter> parameter. The functions
291 <function>sd_bus_error_set_errno()</function>,
292 <function>sd_bus_error_set_errnof()</function> and
293 <function>sd_bus_error_set_errnofv()</function>, when successful,
294 return the negative value of the <parameter>error</parameter>
295 parameter. If an error occurs, one of the negative error values
296 listed below will be returned.</para>
298 <para><function>sd_bus_error_get_errno()</function> returns
299 <constant>false</constant> when <parameter>e</parameter> is
300 <constant>NULL</constant>, and a positive errno value mapped from
301 <parameter>e->name</parameter> otherwise.</para>
303 <para><function>sd_bus_error_copy()</function> returns 0 or a
304 positive integer on success, and a negative error value converted
305 from the error name otherwise.</para>
307 <para><function>sd_bus_error_is_set()</function> returns a
308 non-zero value when <parameter>e</parameter> and the
309 <structfield>name</structfield> field are
310 non-<constant>NULL</constant>, zero otherwise.</para>
312 <para><function>sd_bus_error_has_name()</function> returns a
313 non-zero value when <parameter>e</parameter> is
314 non-<constant>NULL</constant> and the
315 <structfield>name</structfield> field is equal to
316 <parameter>name</parameter>, zero otherwise.</para>
320 <title>Reference ownership</title>
321 <para><structname>sd_bus_error</structname> is not reference
322 counted. Users should destroy resources held by it by calling
323 <function>sd_bus_error_free()</function>. Usually, error structures
324 are allocated on the stack or passed in as function parameters,
325 but they may also be allocated dynamically, in which case it is
326 the duty of the caller to <citerefentry
327 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
328 the memory held by the structure itself after freeing its contents
329 with <function>sd_bus_error_free()</function>.</para>
333 <title>Errors</title>
335 <para>Returned errors may indicate the following problems:</para>
340 <term><constant>-EINVAL</constant></term>
342 <listitem><para>Error was already set in
343 <structname>sd_bus_error</structname> structure when one the
344 error-setting functions was called.</para></listitem>
348 <term><constant>-ENOMEM</constant></term>
350 <listitem><para>Memory allocation failed.</para></listitem>
355 <xi:include href="libelogind-pkgconfig.xml" />
358 <title>See Also</title>
361 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
362 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
363 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
364 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
365 <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
366 <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>