chiark / gitweb /
nspawn,man: use a common vocabulary when referring to selinux security contexts
[elogind.git] / man / sd_bus_error.xml
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">
4
5 <!--
6 This file is part of systemd.
7
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="sd_bus_error">
25
26   <refentryinfo>
27     <title>sd_bus_error</title>
28     <productname>systemd</productname>
29
30     <authorgroup>
31       <author>
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>
36       </author>
37     </authorgroup>
38   </refentryinfo>
39
40   <refmeta>
41     <refentrytitle>sd_bus_error</refentrytitle>
42     <manvolnum>3</manvolnum>
43   </refmeta>
44
45   <refnamediv>
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>
56
57     <refpurpose>sd-bus error handling</refpurpose>
58   </refnamediv>
59
60   <refsynopsisdiv>
61     <funcsynopsis>
62       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
63
64       <funcsynopsisinfo>typedef struct {
65         const char *name;
66         const char *message;
67         ...
68 } sd_bus_error;</funcsynopsisinfo>
69
70       <para>
71         <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant>
72       </para>
73       <para>
74         <constant>SD_BUS_ERROR_NULL</constant>
75       </para>
76
77       <funcprototype>
78         <funcdef>int <function>sd_bus_error_free</function></funcdef>
79         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
80       </funcprototype>
81
82       <funcprototype>
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>
87       </funcprototype>
88
89       <funcprototype>
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>
95       </funcprototype>
96
97       <funcprototype>
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>
102       </funcprototype>
103
104       <funcprototype>
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>
108       </funcprototype>
109
110       <funcprototype>
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>
116       </funcprototype>
117
118       <funcprototype>
119         <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
120         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
121       </funcprototype>
122
123       <funcprototype>
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>
127       </funcprototype>
128
129       <funcprototype>
130         <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
131         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
132       </funcprototype>
133
134       <funcprototype>
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>
138       </funcprototype>
139     </funcsynopsis>
140
141     <para>
142       <constant>SD_BUS_ERROR_FAILED</constant>
143     </para>
144     <para>
145       <constant>SD_BUS_ERROR_NO_MEMORY</constant>
146     </para>
147     <para>
148       <constant>SD_BUS_ERROR_SERVICE_UNKNOWN</constant>
149     </para>
150     <para>
151       <constant>SD_BUS_ERROR_NAME_HAS_NO_OWNER</constant>
152     </para>
153     <para>
154       <constant>SD_BUS_ERROR_NO_REPLY</constant>
155     </para>
156     <para>
157       <constant>SD_BUS_ERROR_IO_ERROR</constant>
158     </para>
159     <para>
160       <constant>SD_BUS_ERROR_BAD_ADDRESS</constant>
161     </para>
162     <para>
163       <constant>SD_BUS_ERROR_NOT_SUPPORTED</constant>
164     </para>
165     <para>
166       <constant>SD_BUS_ERROR_LIMITS_EXCEEDED</constant>
167     </para>
168     <para>
169       <constant>SD_BUS_ERROR_ACCESS_DENIED</constant>
170     </para>
171     <para>
172       <constant>SD_BUS_ERROR_AUTH_FAILED</constant>
173     </para>
174     <para>
175       <constant>SD_BUS_ERROR_NO_SERVER</constant>
176     </para>
177     <para>
178       <constant>SD_BUS_ERROR_TIMEOUT</constant>
179     </para>
180     <para>
181       <constant>SD_BUS_ERROR_NO_NETWORK</constant>
182     </para>
183     <para>
184       <constant>SD_BUS_ERROR_ADDRESS_IN_USE</constant>
185     </para>
186     <para>
187       <constant>SD_BUS_ERROR_DISCONNECTED</constant>
188     </para>
189     <para>
190       <constant>SD_BUS_ERROR_INVALID_ARGS</constant>
191     </para>
192     <para>
193       <constant>SD_BUS_ERROR_FILE_NOT_FOUND</constant>
194     </para>
195     <para>
196       <constant>SD_BUS_ERROR_FILE_EXISTS</constant>
197     </para>
198     <para>
199       <constant>SD_BUS_ERROR_UNKNOWN_METHOD</constant>
200     </para>
201     <para>
202       <constant>SD_BUS_ERROR_UNKNOWN_OBJECT</constant>
203     </para>
204     <para>
205       <constant>SD_BUS_ERROR_UNKNOWN_INTERFACE</constant>
206     </para>
207     <para>
208       <constant>SD_BUS_ERROR_UNKNOWN_PROPERTY</constant>
209     </para>
210     <para>
211       <constant>SD_BUS_ERROR_PROPERTY_READ_ONLY</constant>
212     </para>
213     <para>
214       <constant>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</constant>
215     </para>
216     <para>
217       <constant>SD_BUS_ERROR_INVALID_SIGNATURE</constant>
218     </para>
219     <para>
220       <constant>SD_BUS_ERROR_INCONSISTENT_MESSAGE</constant>
221     </para>
222     <para>
223       <constant>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</constant>
224     </para>
225     <para>
226       <constant>SD_BUS_ERROR_MATCH_RULE_INVALID</constant>
227     </para>
228
229   </refsynopsisdiv>
230
231   <refsect1>
232     <title>Description</title>
233
234     <para><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. Field <structfield>name</structfield> 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>
245
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 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>
258
259     <para>If <parameter>e</parameter> is not
260     <constant>NULL</constant>, <structfield>name</structfield> and
261     <structfield>message</structfield> will be filled-in in the
262     <structname>sd_bus_error</structname> structure
263     <parameter>e</parameter> points at. 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>
270
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>
276
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>
281
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.
289     </para>
290
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>
298
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
303     returned.</para>
304
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     Otherwie they wil be copied.</para>
311
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>
316
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>
321
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>
327   </refsect1>
328
329   <refsect1>
330     <title>Return Value</title>
331
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>
342
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>
347
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>
351
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>
356
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>
362   </refsect1>
363
364   <refsect1>
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>
369   </refsect1>
370
371   <refsect1>
372     <title>Errors</title>
373
374     <para>Returned errors may indicate the following problems:</para>
375
376     <variablelist>
377
378       <varlistentry>
379         <term><varname>-EINVAL</varname></term>
380
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>
384       </varlistentry>
385
386       <varlistentry>
387         <term><varname>-ENOMEM</varname></term>
388
389         <listitem><para>Memory allocation failed.</para></listitem>
390       </varlistentry>
391     </variablelist>
392   </refsect1>
393
394   <refsect1>
395     <title>Notes</title>
396
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>
401     file.</para>
402   </refsect1>
403
404   <refsect1>
405     <title>See Also</title>
406
407     <para>
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>
412     </para>
413   </refsect1>
414
415 </refentry>