1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_bus_error</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
a.headerlink {
color: #c60f0f;
font-size: 0.8em;
padding: 0 4px 0 4px;
text-decoration: none;
visibility: hidden;
}
a.headerlink:hover {
background-color: #c60f0f;
color: white;
}
h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
visibility: visible;
}
</style><a href="index.html">Index </a>·
<a href="systemd.directives.html">Directives </a>·
<a href="../python-systemd/index.html">Python </a>·
<span style="float:right">systemd 221</span><hr><div class="refentry"><a name="sd_bus_error"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_bus_error, sd_bus_error_free, sd_bus_error_set, sd_bus_error_set_const, sd_bus_error_set_errno, sd_bus_error_set_errnof, sd_bus_error_get_errno, sd_bus_error_copy, sd_bus_error_is_set, sd_bus_error_has_name — sd-bus error handling</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <systemd/sd-bus.h></pre><pre class="funcsynopsisinfo">typedef struct {
const char *name;
const char *message;
...
} sd_bus_error;</pre><p>
<code class="constant">SD_BUS_ERROR_MAKE_CONST(<em class="replaceable"><code>name</code></em>, <em class="replaceable"><code>message</code></em>)</code>
</p><p>
<code class="constant">SD_BUS_ERROR_NULL</code>
</p><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_free</b>(</code></td><td>sd_bus_error *<var class="pdparam">e</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_set</b>(</code></td><td>sd_bus_error *<var class="pdparam">e</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">message</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_setf</b>(</code></td><td>sd_bus_error *<var class="pdparam">e</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">format</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_set_const</b>(</code></td><td>sd_bus_error *<var class="pdparam">e</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">message</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_set_errno</b>(</code></td><td>sd_bus_error *<var class="pdparam">e</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">error</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_set_errnof</b>(</code></td><td>sd_bus_error *<var class="pdparam">e</var>, </td></tr><tr><td> </td><td>int <var class="pdparam">error</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">format</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_get_errno</b>(</code></td><td>const sd_bus_error *<var class="pdparam">e</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_copy</b>(</code></td><td>sd_bus_error *<var class="pdparam">dst</var>, </td></tr><tr><td> </td><td>const sd_bus_error *<var class="pdparam">e</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_is_set</b>(</code></td><td>const sd_bus_error *<var class="pdparam">e</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_error_has_name</b>(</code></td><td>const sd_bus_error *<var class="pdparam">e</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">name</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
<code class="constant">SD_BUS_ERROR_FAILED</code>
</p><p>
<code class="constant">SD_BUS_ERROR_NO_MEMORY</code>
</p><p>
<code class="constant">SD_BUS_ERROR_SERVICE_UNKNOWN</code>
</p><p>
<code class="constant">SD_BUS_ERROR_NAME_HAS_NO_OWNER</code>
</p><p>
<code class="constant">SD_BUS_ERROR_NO_REPLY</code>
</p><p>
<code class="constant">SD_BUS_ERROR_IO_ERROR</code>
</p><p>
<code class="constant">SD_BUS_ERROR_BAD_ADDRESS</code>
</p><p>
<code class="constant">SD_BUS_ERROR_NOT_SUPPORTED</code>
</p><p>
<code class="constant">SD_BUS_ERROR_LIMITS_EXCEEDED</code>
</p><p>
<code class="constant">SD_BUS_ERROR_ACCESS_DENIED</code>
</p><p>
<code class="constant">SD_BUS_ERROR_AUTH_FAILED</code>
</p><p>
<code class="constant">SD_BUS_ERROR_NO_SERVER</code>
</p><p>
<code class="constant">SD_BUS_ERROR_TIMEOUT</code>
</p><p>
<code class="constant">SD_BUS_ERROR_NO_NETWORK</code>
</p><p>
<code class="constant">SD_BUS_ERROR_ADDRESS_IN_USE</code>
</p><p>
<code class="constant">SD_BUS_ERROR_DISCONNECTED</code>
</p><p>
<code class="constant">SD_BUS_ERROR_INVALID_ARGS</code>
</p><p>
<code class="constant">SD_BUS_ERROR_FILE_NOT_FOUND</code>
</p><p>
<code class="constant">SD_BUS_ERROR_FILE_EXISTS</code>
</p><p>
<code class="constant">SD_BUS_ERROR_UNKNOWN_METHOD</code>
</p><p>
<code class="constant">SD_BUS_ERROR_UNKNOWN_OBJECT</code>
</p><p>
<code class="constant">SD_BUS_ERROR_UNKNOWN_INTERFACE</code>
</p><p>
<code class="constant">SD_BUS_ERROR_UNKNOWN_PROPERTY</code>
</p><p>
<code class="constant">SD_BUS_ERROR_PROPERTY_READ_ONLY</code>
</p><p>
<code class="constant">SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</code>
</p><p>
<code class="constant">SD_BUS_ERROR_INVALID_SIGNATURE</code>
</p><p>
<code class="constant">SD_BUS_ERROR_INCONSISTENT_MESSAGE</code>
</p><p>
<code class="constant">SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</code>
</p><p>
<code class="constant">SD_BUS_ERROR_MATCH_RULE_INVALID</code>
</p></div><div class="refsect1"><a name="idm47840597503248"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>The <span class="structname">sd_bus_error</span> structure carries
information for a <code class="filename">sd-bus</code> error. The
functions described below can be used to set and query fields in
this structure. The <em class="structfield"><code>name</code></em> field contains a
short identifier of an error. It should follow the rules for error
names described in the D-Bus specification, subsection <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names" target="_top">Valid
Names</a>. The <em class="structfield"><code>message</code></em> is a human
readable string describing the details. When no longer necessary,
resources held by this structure should be destroyed with
<code class="function">sd_bus_error_free</code>.</p><p><code class="function">sd_bus_error_set</code> will return an
errno-like negative value returned based on parameter
<em class="parameter"><code>name</code></em> (see
<a href="http://man7.org/linux/man-pages/man3/errno.3.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>).
Various well-known D-Bus errors are converted to specific values,
and the remaining ones to <code class="constant">-ENXIO</code>. Well-known
D-Bus error names are available as constants
<code class="constant">SD_BUS_ERROR_FAILED</code>, etc., listed above. If
<em class="parameter"><code>name</code></em> is <code class="constant">NULL</code>, it is
assumed that no error occurred, and 0 is returned. This means that
this function may be conveniently used in a
<code class="function">return</code> statement.</p><p>If <em class="parameter"><code>e</code></em> is not
<code class="constant">NULL</code>, <em class="structfield"><code>name</code></em> and
<em class="structfield"><code>message</code></em> in the
<span class="structname">sd_bus_error</span> structure
<em class="parameter"><code>e</code></em> points at will be filled in. As described above,
<em class="parameter"><code>name</code></em> may be <code class="constant">NULL</code>,
which is treated as no error. Parameter
<em class="parameter"><code>message</code></em> may also be
<code class="constant">NULL</code>, in which case no message is specified.
<code class="function">sd_bus_error_set</code> will make internal copies of
specified strings.</p><p><code class="function">sd_bus_error_setf</code> is similar to
<code class="function">sd_bus_error_set</code>, but takes a
<a href="http://man7.org/linux/man-pages/man3/printf.3.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a>
format string and corresponding arguments to generate
<span class="structname">message</span>.</p><p><code class="function">sd_bus_error_set_const</code> is similar to
<code class="function">sd_bus_error_set</code>, but string parameters are
not copied internally, and must remain valid for the lifetime of
<em class="parameter"><code>e</code></em>.</p><p><code class="function">sd_bus_error_set_errno</code> will set
<em class="structfield"><code>name</code></em> based on an errno-like value.
<a href="http://linux.die.net/man/3/strerror"><span class="citerefentry"><span class="refentrytitle">strerror</span>(3)</span></a>
will be used to set <em class="structfield"><code>message</code></em>. Well-known
D-Bus error names will be used for <em class="structfield"><code>name</code></em>
if available, otherwise a name in the
"<code class="literal">System.Error</code>" namespace will be generated.
</p><p><code class="function">sd_bus_error_set_errnof</code> is similar to
<code class="function">sd_bus_error_set_errno</code>, but in addition to
<em class="parameter"><code>name</code></em>, takes a
<a href="http://man7.org/linux/man-pages/man3/printf.3.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a>
format and corresponding arguments.
<em class="structfield"><code>name</code></em> will be generated from
<em class="parameter"><code>format</code></em> and the arguments.</p><p><code class="function">sd_bus_error_get_errno</code> will convert
<span class="structname">e->name</span> to an errno-like value using the
same rules as <code class="function">sd_bus_error_set</code>. If
<em class="parameter"><code>e</code></em> is <code class="constant">NULL</code>, 0 will be
returned.</p><p><code class="function">sd_bus_error_copy</code> will initialize
<em class="parameter"><code>dst</code></em> using the values in
<em class="parameter"><code>e</code></em>. If the strings in
<em class="parameter"><code>e</code></em> were set using
<code class="function">sd_bus_set_error_const</code>, they will be shared.
Otherwise, they will be copied.</p><p><code class="function">sd_bus_error_is_set</code> will return
<code class="constant">true</code> if <em class="parameter"><code>e</code></em> is
non-<code class="constant">NULL</code> and an error has been set,
<code class="constant">false</code> otherwise.</p><p><code class="function">sd_bus_error_has_name</code> will return true
if <em class="parameter"><code>e</code></em> is non-<code class="constant">NULL</code> and
an error with the same <em class="parameter"><code>name</code></em> has been set,
<code class="constant">false</code> otherwise.</p><p><code class="function">sd_bus_error_free</code> will destroy resources
held by <em class="parameter"><code>e</code></em>. The parameter itself will not
be deallocated, and must be
<a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>d
by the caller if necessary.</p></div><div class="refsect1"><a name="idm47840597460368"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p>Functions <code class="function">sd_bus_error_set</code>,
<code class="function">sd_bus_error_setf</code>,
<code class="function">sd_bus_error_set_const</code>, when successful,
return the negative errno value corresponding to the
<em class="parameter"><code>name</code></em> parameter. Functions
<code class="function">sd_bus_error_set_errno</code> and
<code class="function">sd_bus_error_set_errnof</code>, when successful,
return the value of the <em class="parameter"><code>errno</code></em> parameter. If
an error occurs, one of the negative error values listed below
will be returned.</p><p><code class="function">sd_bus_error_get_errno</code> returns
<code class="constant">false</code> when <em class="parameter"><code>e</code></em> is
<code class="constant">NULL</code>, and a positive errno value mapped from
<em class="parameter"><code>e->name</code></em> otherwise.</p><p><code class="function">sd_bus_error_copy</code> returns 0 or a
positive integer on success, and one of the negative error values
listed below otherwise.</p><p><code class="function">sd_bus_error_is_set</code> returns
<code class="constant">true</code> when <em class="parameter"><code>e</code></em> and
<em class="parameter"><code>e->name</code></em> are non-<code class="constant">NULL</code>,
<code class="constant">false</code> otherwise.</p><p><code class="function">sd_bus_error_has_name</code> returns
<code class="constant">true</code> when <em class="parameter"><code>e</code></em> is
non-<code class="constant">NULL</code> and <em class="parameter"><code>e->name</code></em>
is equal to <em class="parameter"><code>name</code></em>,
<code class="constant">false</code> otherwise.</p></div><div class="refsect1"><a name="idm47840597443552"></a><h2 id="Reference ownership">Reference ownership<a class="headerlink" title="Permalink to this headline" href="#Reference%20ownership">¶</a></h2><p><span class="structname">sd_bus_error</span> is not reference
counted. Users should destroy resources held by it by calling
<code class="function">sd_bus_error_free</code>.</p></div><div class="refsect1"><a name="idm47840597441408"></a><h2 id="Errors">Errors<a class="headerlink" title="Permalink to this headline" href="#Errors">¶</a></h2><p>Returned errors may indicate the following problems:</p><div class="variablelist"><dl class="variablelist"><dt id="-EINVAL"><span class="term"><code class="constant">-EINVAL</code></span><a class="headerlink" title="Permalink to this term" href="#-EINVAL">¶</a></dt><dd><p>Error was already set in
<span class="structname">sd_bus_error</span> structure when one the
error-setting functions was called.</p></dd><dt id="-ENOMEM"><span class="term"><code class="constant">-ENOMEM</code></span><a class="headerlink" title="Permalink to this term" href="#-ENOMEM">¶</a></dt><dd><p>Memory allocation failed.</p></dd></dl></div></div><div class="refsect1"><a name="idm47840597436672"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p><code class="function">sd_bus_set_error()</code> and other functions
described here are available as a shared library, which can be
compiled and linked to with the
<code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
file.</p></div><div class="refsect1"><a name="idm47840597433488"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
<a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>,
<a href="http://man7.org/linux/man-pages/man3/errno.3.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>,
<a href="http://linux.die.net/man/3/strerror"><span class="citerefentry"><span class="refentrytitle">strerror</span>(3)</span></a>
</p></div></div></body></html>
|
