]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/sd_bus_error.xml
verify: use manager_load_startable_unit_or_warn() to load units for verification
[thirdparty/systemd.git] / man / sd_bus_error.xml
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">
4
5 <!--
6 SPDX-License-Identifier: LGPL-2.1+
7
8 This file is part of systemd.
9
10 Copyright 2014 Zbigniew Jędrzejewski-Szmek
11
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
16
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
21
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 -->
25
26 <refentry id="sd_bus_error">
27
28 <refentryinfo>
29 <title>sd_bus_error</title>
30 <productname>systemd</productname>
31
32 <authorgroup>
33 <author>
34 <contrib>A monkey with a typewriter</contrib>
35 <firstname>Zbigniew</firstname>
36 <surname>Jędrzejewski-Szmek</surname>
37 <email>zbyszek@in.waw.pl</email>
38 </author>
39 </authorgroup>
40 </refentryinfo>
41
42 <refmeta>
43 <refentrytitle>sd_bus_error</refentrytitle>
44 <manvolnum>3</manvolnum>
45 </refmeta>
46
47 <refnamediv>
48 <refname>sd_bus_error</refname>
49 <refname>SD_BUS_ERROR_MAKE_CONST</refname>
50 <refname>SD_BUS_ERROR_NULL</refname>
51 <refname>sd_bus_error_free</refname>
52 <refname>sd_bus_error_set</refname>
53 <refname>sd_bus_error_setf</refname>
54 <refname>sd_bus_error_set_const</refname>
55 <refname>sd_bus_error_set_errno</refname>
56 <refname>sd_bus_error_set_errnof</refname>
57 <refname>sd_bus_error_set_errnofv</refname>
58 <refname>sd_bus_error_get_errno</refname>
59 <refname>sd_bus_error_copy</refname>
60 <refname>sd_bus_error_is_set</refname>
61 <refname>sd_bus_error_has_name</refname>
62
63 <refpurpose>sd-bus error handling</refpurpose>
64 </refnamediv>
65
66 <refsynopsisdiv>
67 <funcsynopsis>
68 <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
69
70 <funcsynopsisinfo>typedef struct {
71 const char *name;
72 const char *message;
73
74 } sd_bus_error;</funcsynopsisinfo>
75
76 <para>
77 <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant>
78 </para>
79 <para>
80 <constant>SD_BUS_ERROR_NULL</constant>
81 </para>
82
83 <funcprototype>
84 <funcdef>void <function>sd_bus_error_free</function></funcdef>
85 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
86 </funcprototype>
87
88 <funcprototype>
89 <funcdef>int <function>sd_bus_error_set</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>
93 </funcprototype>
94
95 <funcprototype>
96 <funcdef>int <function>sd_bus_error_setf</function></funcdef>
97 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
98 <paramdef>const char *<parameter>name</parameter></paramdef>
99 <paramdef>const char *<parameter>format</parameter></paramdef>
100 <paramdef></paramdef>
101 </funcprototype>
102
103 <funcprototype>
104 <funcdef>int <function>sd_bus_error_set_const</function></funcdef>
105 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
106 <paramdef>const char *<parameter>name</parameter></paramdef>
107 <paramdef>const char *<parameter>message</parameter></paramdef>
108 </funcprototype>
109
110 <funcprototype>
111 <funcdef>int <function>sd_bus_error_set_errno</function></funcdef>
112 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
113 <paramdef>int <parameter>error</parameter></paramdef>
114 </funcprototype>
115
116 <funcprototype>
117 <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef>
118 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
119 <paramdef>int <parameter>error</parameter></paramdef>
120 <paramdef>const char *<parameter>format</parameter></paramdef>
121 <paramdef></paramdef>
122 </funcprototype>
123
124 <funcprototype>
125 <funcdef>int <function>sd_bus_error_set_errnofv</function></funcdef>
126 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
127 <paramdef>int <parameter>error</parameter></paramdef>
128 <paramdef>const char *<parameter>format</parameter></paramdef>
129 <paramdef>va_list ap</paramdef>
130 </funcprototype>
131
132 <funcprototype>
133 <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
134 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
135 </funcprototype>
136
137 <funcprototype>
138 <funcdef>int <function>sd_bus_error_copy</function></funcdef>
139 <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef>
140 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
141 </funcprototype>
142
143 <funcprototype>
144 <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
145 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
146 </funcprototype>
147
148 <funcprototype>
149 <funcdef>int <function>sd_bus_error_has_name</function></funcdef>
150 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
151 <paramdef>const char *<parameter>name</parameter></paramdef>
152 </funcprototype>
153 </funcsynopsis>
154
155 </refsynopsisdiv>
156
157 <refsect1>
158 <title>Description</title>
159
160 <para>The <structname>sd_bus_error</structname> structure carries
161 information about a D-Bus error condition. The functions described
162 below may be used to set and query fields in this structure. The
163 <structfield>name</structfield> field contains a short identifier
164 of an error. It should follow the rules for error names described
165 in the D-Bus specification, subsection <ulink
166 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
167 Names</ulink>. A number of common, standardized error names are
168 described in
169 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
170 but additional domain-specific errors may be defined by
171 applications. The <structfield>message</structfield> field usually
172 contains a human-readable string describing the details, but might
173 be NULL. An unset <structname>sd_bus_error</structname> structure
174 should have both fields initialized to NULL. Set an error
175 structure to <constant>SD_BUS_ERROR_NULL</constant> in order to
176 reset both fields to NULL. When no longer necessary, resources
177 held by the <structname>sd_bus_error</structname>structure should
178 be destroyed with <function>sd_bus_error_free()</function>.</para>
179
180 <para><function>sd_bus_error_set()</function> sets an error
181 structure to the specified name and message strings. The strings
182 will be copied into internal, newly allocated memory. It is
183 essential to free the error structure again when it is not
184 required anymore (see above). The function will return an
185 <varname>errno</varname>-like negative value (see <citerefentry
186 project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
187 determined from the specified error name. Various well-known
188 D-Bus errors are converted to well-known <varname>errno</varname>
189 counterparts, and the other ones to <constant>-EIO</constant>. See
190 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>
191 for a list of well-known error names. Additional error mappings
192 may be defined with
193 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
194 <parameter>e</parameter> is NULL, no error structure is initialized,
195 but the error is still converted into an
196 <varname>errno</varname>-style error. If
197 <parameter>name</parameter> is <constant>NULL</constant>, it is
198 assumed that no error occurred, and 0 is returned. This means that
199 this function may be conveniently used in a
200 <function>return</function> statement. If
201 <parameter>message</parameter> is NULL, no message is set. This
202 call can fail if no memory may be allocated for the name and
203 message strings, in which case an
204 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set
205 instead and -ENOMEM be returned. Do not use this call on error
206 structures that are already initialized. If you intend to reuse an
207 error structure, free the old data stored in it with
208 <function>sd_bus_error_free()</function> first.</para>
209
210 <para><function>sd_bus_error_setf()</function> is similar to
211 <function>sd_bus_error_set()</function>, but takes a <citerefentry
212 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
213 format string and corresponding arguments to generate the
214 <structfield>message</structfield> field.</para>
215
216 <para><function>sd_bus_error_set_const()</function> is similar to
217 <function>sd_bus_error_set()</function>, but the string parameters
218 are not copied internally, and must hence remain constant and
219 valid for the lifetime of <parameter>e</parameter>. Use this call
220 to avoid memory allocations when setting error structures. Since
221 this call does not allocate memory, it will not fail with an
222 out-of-memory condition as
223 <function>sd_bus_error_set()</function> can, as described
224 above. Alternatively, the
225 <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used
226 to generate a literal, constant bus error structure
227 on-the-fly.</para>
228
229 <para><function>sd_bus_error_set_errno()</function> will set
230 <structfield>name</structfield> from an
231 <varname>errno</varname>-like value that is converted to a D-Bus
232 error. <citerefentry
233 project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
234 will be used to set <structfield>message</structfield>. Well-known
235 D-Bus error names will be used for <structfield>name</structfield>
236 if applicable, otherwise a name in the
237 <literal>System.Error.</literal> namespace will be generated. The
238 sign of the specified error number is ignored. The absolute value
239 is used implicitly. The call always returns a negative value, for
240 convenient usage in <function>return</function> statements. This
241 call might fail due to lack of memory, in which case an
242 <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead,
243 and -ENOMEM is returned.</para>
244
245 <para><function>sd_bus_error_set_errnof()</function> is similar to
246 <function>sd_bus_error_set_errno()</function>, but in addition to
247 <parameter>error</parameter>, takes a <citerefentry
248 project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
249 format string and corresponding arguments. The
250 <structfield>message</structfield> field will be generated from
251 <parameter>format</parameter> and the arguments.</para>
252
253 <para><function>sd_bus_error_set_errnofv()</function> is similar to
254 <function>sd_bus_error_set_errnof()</function>, but takes the
255 format string parameters as <citerefentry
256 project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
257 parameter list.</para>
258
259 <para><function>sd_bus_error_get_errno()</function> converts the
260 <structfield>name</structfield> field of an error structure to an
261 <varname>errno</varname>-like (positive) value using the same
262 rules as <function>sd_bus_error_set()</function>. If
263 <parameter>e</parameter> is <constant>NULL</constant>, 0 will be
264 returned.</para>
265
266 <para><function>sd_bus_error_copy()</function> will initialize
267 <parameter>dst</parameter> using the values in
268 <parameter>e</parameter>. If the strings in
269 <parameter>e</parameter> were set using
270 <function>sd_bus_error_set_const()</function>, they will be shared.
271 Otherwise, they will be copied. Returns a converted
272 <varname>errno</varname>-like, negative error code.</para>
273
274 <para><function>sd_bus_error_is_set()</function> will return a
275 non-zero value if <parameter>e</parameter> is
276 non-<constant>NULL</constant> and an error has been set,
277 <constant>false</constant> otherwise.</para>
278
279 <para><function>sd_bus_error_has_name()</function> will return a
280 non-zero value if <parameter>e</parameter> is
281 non-<constant>NULL</constant> and an error with the same
282 <parameter>name</parameter> has been set,
283 <constant>false</constant> otherwise.</para>
284
285 <para><function>sd_bus_error_free()</function> will destroy
286 resources held by <parameter>e</parameter>. The parameter itself
287 will not be deallocated, and must be <citerefentry
288 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
289 by the caller if necessary. The function may also be called safely
290 on unset errors (error structures with both fields set to NULL),
291 in which case it performs no operation. This call will reset the
292 error structure after freeing the data, so that all fields are set
293 to NULL. The structure may be reused afterwards.</para>
294 </refsect1>
295
296 <refsect1>
297 <title>Return Value</title>
298
299 <para>The functions <function>sd_bus_error_set()</function>,
300 <function>sd_bus_error_setf()</function>, and
301 <function>sd_bus_error_set_const()</function>, when successful,
302 return the negative errno value corresponding to the
303 <parameter>name</parameter> parameter. The functions
304 <function>sd_bus_error_set_errno()</function>,
305 <function>sd_bus_error_set_errnof()</function> and
306 <function>sd_bus_error_set_errnofv()</function>, when successful,
307 return the negative value of the <parameter>error</parameter>
308 parameter. If an error occurs, one of the negative error values
309 listed below will be returned.</para>
310
311 <para><function>sd_bus_error_get_errno()</function> returns
312 <constant>false</constant> when <parameter>e</parameter> is
313 <constant>NULL</constant>, and a positive errno value mapped from
314 <parameter>e-&gt;name</parameter> otherwise.</para>
315
316 <para><function>sd_bus_error_copy()</function> returns 0 or a
317 positive integer on success, and a negative error value converted
318 from the error name otherwise.</para>
319
320 <para><function>sd_bus_error_is_set()</function> returns a
321 non-zero value when <parameter>e</parameter> and the
322 <structfield>name</structfield> field are
323 non-<constant>NULL</constant>, zero otherwise.</para>
324
325 <para><function>sd_bus_error_has_name()</function> returns a
326 non-zero value when <parameter>e</parameter> is
327 non-<constant>NULL</constant> and the
328 <structfield>name</structfield> field is equal to
329 <parameter>name</parameter>, zero otherwise.</para>
330 </refsect1>
331
332 <refsect1>
333 <title>Reference ownership</title>
334 <para><structname>sd_bus_error</structname> is not reference
335 counted. Users should destroy resources held by it by calling
336 <function>sd_bus_error_free()</function>. Usually, error structures
337 are allocated on the stack or passed in as function parameters,
338 but they may also be allocated dynamically, in which case it is
339 the duty of the caller to <citerefentry
340 project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
341 the memory held by the structure itself after freeing its contents
342 with <function>sd_bus_error_free()</function>.</para>
343 </refsect1>
344
345 <refsect1>
346 <title>Errors</title>
347
348 <para>Returned errors may indicate the following problems:</para>
349
350 <variablelist>
351
352 <varlistentry>
353 <term><constant>-EINVAL</constant></term>
354
355 <listitem><para>Error was already set in
356 <structname>sd_bus_error</structname> structure when one the
357 error-setting functions was called.</para></listitem>
358 </varlistentry>
359
360 <varlistentry>
361 <term><constant>-ENOMEM</constant></term>
362
363 <listitem><para>Memory allocation failed.</para></listitem>
364 </varlistentry>
365 </variablelist>
366 </refsect1>
367
368 <refsect1>
369 <title>Notes</title>
370
371 <para><function>sd_bus_set_error()</function> and other functions
372 described here are available as a shared library, which can be
373 compiled and linked to with the
374 <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
375 file.</para>
376 </refsect1>
377
378 <refsect1>
379 <title>See Also</title>
380
381 <para>
382 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
383 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
384 <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
385 <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
386 <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
387 <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
388 </para>
389 </refsect1>
390
391 </refentry>