1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
24 <refentry id="sd_bus_error" conditional="ENABLE_KDBUS">
27 <title>sd_bus_error</title>
28 <productname>systemd</productname>
32 <contrib>A monkey with a typewriter</contrib>
33 <firstname>Zbigniew</firstname>
34 <surname>Jędrzejewski-Szmek</surname>
35 <email>zbyszek@in.waw.pl</email>
41 <refentrytitle>sd_bus_error</refentrytitle>
42 <manvolnum>3</manvolnum>
46 <refname>sd_bus_error</refname>
47 <refname>sd_bus_error_free</refname>
48 <refname>sd_bus_error_set</refname>
49 <refname>sd_bus_error_set_const</refname>
50 <refname>sd_bus_error_set_errno</refname>
51 <refname>sd_bus_error_set_errnof</refname>
52 <refname>sd_bus_error_get_errno</refname>
53 <refname>sd_bus_error_copy</refname>
54 <refname>sd_bus_error_is_set</refname>
55 <refname>sd_bus_error_has_name</refname>
57 <refpurpose>sd-bus error handling</refpurpose>
62 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
64 <funcsynopsisinfo>typedef struct {
68 } sd_bus_error;</funcsynopsisinfo>
71 <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant>
74 <constant>SD_BUS_ERROR_NULL</constant>
78 <funcdef>int <function>sd_bus_error_free</function></funcdef>
79 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
83 <funcdef>int <function>sd_bus_error_set</function></funcdef>
84 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
85 <paramdef>const char *<parameter>name</parameter></paramdef>
86 <paramdef>const char *<parameter>message</parameter></paramdef>
90 <funcdef>int <function>sd_bus_error_setf</function></funcdef>
91 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
92 <paramdef>const char *<parameter>name</parameter></paramdef>
93 <paramdef>const char *<parameter>format</parameter></paramdef>
94 <paramdef>...</paramdef>
98 <funcdef>int <function>sd_bus_error_set_const</function></funcdef>
99 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
100 <paramdef>const char *<parameter>name</parameter></paramdef>
101 <paramdef>const char *<parameter>message</parameter></paramdef>
105 <funcdef>int <function>sd_bus_error_set_errno</function></funcdef>
106 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
107 <paramdef>int <parameter>error</parameter></paramdef>
111 <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef>
112 <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
113 <paramdef>int <parameter>error</parameter></paramdef>
114 <paramdef>const char *<parameter>format</parameter></paramdef>
115 <paramdef>...</paramdef>
119 <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
120 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
124 <funcdef>int <function>sd_bus_error_copy</function></funcdef>
125 <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef>
126 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
130 <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
131 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
135 <funcdef>int <function>sd_bus_error_has_name</function></funcdef>
136 <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
137 <paramdef>const char *<parameter>name</parameter></paramdef>
142 <constant>SD_BUS_ERROR_FAILED</constant>
145 <constant>SD_BUS_ERROR_NO_MEMORY</constant>
148 <constant>SD_BUS_ERROR_SERVICE_UNKNOWN</constant>
151 <constant>SD_BUS_ERROR_NAME_HAS_NO_OWNER</constant>
154 <constant>SD_BUS_ERROR_NO_REPLY</constant>
157 <constant>SD_BUS_ERROR_IO_ERROR</constant>
160 <constant>SD_BUS_ERROR_BAD_ADDRESS</constant>
163 <constant>SD_BUS_ERROR_NOT_SUPPORTED</constant>
166 <constant>SD_BUS_ERROR_LIMITS_EXCEEDED</constant>
169 <constant>SD_BUS_ERROR_ACCESS_DENIED</constant>
172 <constant>SD_BUS_ERROR_AUTH_FAILED</constant>
175 <constant>SD_BUS_ERROR_NO_SERVER</constant>
178 <constant>SD_BUS_ERROR_TIMEOUT</constant>
181 <constant>SD_BUS_ERROR_NO_NETWORK</constant>
184 <constant>SD_BUS_ERROR_ADDRESS_IN_USE</constant>
187 <constant>SD_BUS_ERROR_DISCONNECTED</constant>
190 <constant>SD_BUS_ERROR_INVALID_ARGS</constant>
193 <constant>SD_BUS_ERROR_FILE_NOT_FOUND</constant>
196 <constant>SD_BUS_ERROR_FILE_EXISTS</constant>
199 <constant>SD_BUS_ERROR_UNKNOWN_METHOD</constant>
202 <constant>SD_BUS_ERROR_UNKNOWN_OBJECT</constant>
205 <constant>SD_BUS_ERROR_UNKNOWN_INTERFACE</constant>
208 <constant>SD_BUS_ERROR_UNKNOWN_PROPERTY</constant>
211 <constant>SD_BUS_ERROR_PROPERTY_READ_ONLY</constant>
214 <constant>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</constant>
217 <constant>SD_BUS_ERROR_INVALID_SIGNATURE</constant>
220 <constant>SD_BUS_ERROR_INCONSISTENT_MESSAGE</constant>
223 <constant>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</constant>
226 <constant>SD_BUS_ERROR_MATCH_RULE_INVALID</constant>
232 <title>Description</title>
234 <para>The <structname>sd_bus_error</structname> structure carries
235 information for a <filename>sd-bus</filename> error.
236 Functions described below can be used to set and query fields in
237 this structure. The <structfield>name</structfield> field contains a
238 short identifier of an error. It should follow the rules for error
239 names described in the D-Bus specification, subsection <ulink
240 url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
241 Names</ulink>. The <structfield>message</structfield> is a human
242 readable string describing the details. When no longer necessary,
243 resources held by this structure should be destroyed with
244 <function>sd_bus_error_free</function>.</para>
246 <para><function>sd_bus_error_set</function> will return an
247 errno-like negative value returned based on parameter
248 <parameter>name</parameter> (see
249 <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
250 Various well-known D-Bus errors are converted to specific values,
251 and the remaining ones to <constant>-ENXIO</constant>. Well-known
252 D-Bus error names are available as constants
253 <constant>SD_BUS_ERROR_FAILED</constant>, etc., listed above. If
254 <parameter>name</parameter> is <constant>NULL</constant>, it is
255 assumed that no error occured, and 0 is returned. This means that
256 this function may be conveniently used in a
257 <function>return</function> statement.</para>
259 <para>If <parameter>e</parameter> is not
260 <constant>NULL</constant>, <structfield>name</structfield> and
261 <structfield>message</structfield> in the
262 <structname>sd_bus_error</structname> structure
263 <parameter>e</parameter> points at will be filled in. As described above,
264 <parameter>name</parameter> may be <constant>NULL</constant>,
265 which is treated as no error. Parameter
266 <parameter>message</parameter> may also be
267 <constant>NULL</constant>, in which case no message is specified.
268 <function>sd_bus_error_set</function> will make internal copies of
269 specified strings.</para>
271 <para><function>sd_bus_error_setf</function> is similar to
272 <function>sd_bus_error_set</function>, but takes a
273 <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
274 format string and corresponding arguments to generate
275 <structname>message</structname>.</para>
277 <para><function>sd_bus_error_set_const</function> is similar to
278 <function>sd_bus_error_set</function>, but string parameters are
279 not copied internally, and must remain valid for the lifetime of
280 <parameter>e</parameter>.</para>
282 <para><function>sd_bus_error_set_errno</function> will set
283 <structfield>name</structfield> based on an errno-like value.
284 <citerefentry><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
285 will be used to set <structfield>message</structfield>. Well-known
286 D-Bus error names will be used for <structfield>name</structfield>
287 if available, otherwise a name in the
288 <literal>System.Error</literal> namespace will be generated.
291 <para><function>sd_bus_error_set_errnof</function> is similar to
292 <function>sd_bus_error_set_errno</function>, but in addition to
293 <parameter>name</parameter>, takes a
294 <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
295 format and corresponding arguments.
296 <structfield>name</structfield> will be generated from
297 <parameter>format</parameter> and the arguments.</para>
299 <para><function>sd_bus_error_get_errno</function> is will convert
300 <structname>e->name</structname> to an errno-like value using the
301 same rules as <function>sd_bus_error_set</function>. If
302 <parameter>e</parameter> is <constant>NULL</constant>, 0 will be
305 <para><function>sd_bus_error_copy</function> will initialize
306 <parameter>dst</parameter> using the values in
307 <parameter>e</parameter>. If the strings in
308 <parameter>e</parameter> were set using
309 <function>sd_bus_set_error_const</function>, they will be shared.
310 Otherwise, they will be copied.</para>
312 <para><function>sd_bus_error_is_set</function> will return
313 <constant>true</constant> if <parameter>e</parameter> is
314 non-<constant>NULL</constant> and an error has been set,
315 <constant>false</constant> otherwise.</para>
317 <para><function>sd_bus_error_has_name</function> will return true
318 if <parameter>e</parameter> is non-<constant>NULL</constant> and
319 an error with the same <parameter>name</parameter> has been set,
320 <constant>false</constant> otherwise.</para>
322 <para><function>sd_bus_error_free</function> will destroy resources
323 held by <parameter>e</parameter>. The parameter itself will not
324 be deallocated, and must be
325 <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
326 by the caller if necessary.</para>
330 <title>Return Value</title>
332 <para>Functions <function>sd_bus_error_set</function>,
333 <function>sd_bus_error_setf</function>,
334 <function>sd_bus_error_set_const</function>, when successful,
335 return the negative errno value corresponding to the
336 <parameter>name</parameter> parameter. Functions
337 <function>sd_bus_error_set_errno</function> and
338 <function>sd_bus_error_set_errnof</function>, when successful,
339 return the value of the <parameter>errno</parameter> parameter. If
340 an error occurs, one of the negative error values listed below
341 will be returned.</para>
343 <para><function>sd_bus_error_get_errno</function> returns
344 <constant>false</constant> when <parameter>e</parameter> is
345 <constant>NULL</constant>, and a positive errno value mapped from
346 <parameter>e->name</parameter> otherwise.</para>
348 <para><function>sd_bus_error_copy</function> returns 0 or a
349 positive integer on success, and one of the negative error values
350 listed below otherwise.</para>
352 <para><function>sd_bus_error_is_set</function> returns
353 <constant>true</constant> when <parameter>e</parameter> and
354 <parameter>e->name</parameter> are non-<constant>NULL</constant>,
355 <constant>false</constant> otherwise.</para>
357 <para><function>sd_bus_error_has_name</function> returns
358 <constant>true</constant> when <parameter>e</parameter> is
359 non-<constant>NULL</constant> and <parameter>e->name</parameter>
360 is equal to <parameter>name</parameter>,
361 <constant>false</constant> otherwise.</para>
365 <title>Reference ownership</title>
366 <para><structname>sd_bus_error</structname> is not reference
367 counted. Users should destroy resources held by it by calling
368 <function>sd_bus_error_free</function>.</para>
372 <title>Errors</title>
374 <para>Returned errors may indicate the following problems:</para>
379 <term><varname>-EINVAL</varname></term>
381 <listitem><para>Error was already set in
382 <structname>sd_bus_error</structname> structure when one the
383 error-setting functions was called.</para></listitem>
387 <term><varname>-ENOMEM</varname></term>
389 <listitem><para>Memory allocation failed.</para></listitem>
397 <para><function>sd_bus_set_error()</function> and other functions
398 described here are available as a shared library, which can be
399 compiled and linked to with the
400 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
405 <title>See Also</title>
408 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
409 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
410 <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
411 <citerefentry><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry>