]>
Commit | Line | Data |
---|---|---|
60f067b4 JS |
1 | <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> |
2 | a.headerlink { | |
3 | color: #c60f0f; | |
4 | font-size: 0.8em; | |
5 | padding: 0 4px 0 4px; | |
6 | text-decoration: none; | |
7 | visibility: hidden; | |
8 | } | |
9 | ||
10 | a.headerlink:hover { | |
11 | background-color: #c60f0f; | |
12 | color: white; | |
13 | } | |
14 | ||
15 | h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink { | |
16 | visibility: visible; | |
17 | } | |
18 | </style><a href="index.html">Index </a>· | |
19 | <a href="systemd.directives.html">Directives </a>· | |
20 | <a href="../python-systemd/index.html">Python </a>· | |
21 | <a href="../libudev/index.html">libudev </a>· | |
f47781d8 | 22 | <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 218</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 { |
60f067b4 JS |
23 | const char *name; |
24 | const char *message; | |
25 | ... | |
26 | } sd_bus_error;</pre><p> | |
27 | <code class="constant">SD_BUS_ERROR_MAKE_CONST(<em class="replaceable"><code>name</code></em>, <em class="replaceable"><code>message</code></em>)</code> | |
28 | </p><p> | |
29 | <code class="constant">SD_BUS_ERROR_NULL</code> | |
30 | </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> | |
31 | <code class="constant">SD_BUS_ERROR_FAILED</code> | |
32 | </p><p> | |
33 | <code class="constant">SD_BUS_ERROR_NO_MEMORY</code> | |
34 | </p><p> | |
35 | <code class="constant">SD_BUS_ERROR_SERVICE_UNKNOWN</code> | |
36 | </p><p> | |
37 | <code class="constant">SD_BUS_ERROR_NAME_HAS_NO_OWNER</code> | |
38 | </p><p> | |
39 | <code class="constant">SD_BUS_ERROR_NO_REPLY</code> | |
40 | </p><p> | |
41 | <code class="constant">SD_BUS_ERROR_IO_ERROR</code> | |
42 | </p><p> | |
43 | <code class="constant">SD_BUS_ERROR_BAD_ADDRESS</code> | |
44 | </p><p> | |
45 | <code class="constant">SD_BUS_ERROR_NOT_SUPPORTED</code> | |
46 | </p><p> | |
47 | <code class="constant">SD_BUS_ERROR_LIMITS_EXCEEDED</code> | |
48 | </p><p> | |
49 | <code class="constant">SD_BUS_ERROR_ACCESS_DENIED</code> | |
50 | </p><p> | |
51 | <code class="constant">SD_BUS_ERROR_AUTH_FAILED</code> | |
52 | </p><p> | |
53 | <code class="constant">SD_BUS_ERROR_NO_SERVER</code> | |
54 | </p><p> | |
55 | <code class="constant">SD_BUS_ERROR_TIMEOUT</code> | |
56 | </p><p> | |
57 | <code class="constant">SD_BUS_ERROR_NO_NETWORK</code> | |
58 | </p><p> | |
59 | <code class="constant">SD_BUS_ERROR_ADDRESS_IN_USE</code> | |
60 | </p><p> | |
61 | <code class="constant">SD_BUS_ERROR_DISCONNECTED</code> | |
62 | </p><p> | |
63 | <code class="constant">SD_BUS_ERROR_INVALID_ARGS</code> | |
64 | </p><p> | |
65 | <code class="constant">SD_BUS_ERROR_FILE_NOT_FOUND</code> | |
66 | </p><p> | |
67 | <code class="constant">SD_BUS_ERROR_FILE_EXISTS</code> | |
68 | </p><p> | |
69 | <code class="constant">SD_BUS_ERROR_UNKNOWN_METHOD</code> | |
70 | </p><p> | |
71 | <code class="constant">SD_BUS_ERROR_UNKNOWN_OBJECT</code> | |
72 | </p><p> | |
73 | <code class="constant">SD_BUS_ERROR_UNKNOWN_INTERFACE</code> | |
74 | </p><p> | |
75 | <code class="constant">SD_BUS_ERROR_UNKNOWN_PROPERTY</code> | |
76 | </p><p> | |
77 | <code class="constant">SD_BUS_ERROR_PROPERTY_READ_ONLY</code> | |
78 | </p><p> | |
79 | <code class="constant">SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</code> | |
80 | </p><p> | |
81 | <code class="constant">SD_BUS_ERROR_INVALID_SIGNATURE</code> | |
82 | </p><p> | |
83 | <code class="constant">SD_BUS_ERROR_INCONSISTENT_MESSAGE</code> | |
84 | </p><p> | |
85 | <code class="constant">SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</code> | |
86 | </p><p> | |
87 | <code class="constant">SD_BUS_ERROR_MATCH_RULE_INVALID</code> | |
f47781d8 | 88 | </p></div><div class="refsect1"><a name="idm139886277269328"></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 |
60f067b4 JS |
89 | information for a <code class="filename">sd-bus</code> error. The |
90 | functions described below can be used to set and query fields in | |
91 | this structure. The <em class="structfield"><code>name</code></em> field contains a | |
92 | short identifier of an error. It should follow the rules for error | |
93 | 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 | |
94 | Names</a>. The <em class="structfield"><code>message</code></em> is a human | |
95 | readable string describing the details. When no longer necessary, | |
96 | resources held by this structure should be destroyed with | |
97 | <code class="function">sd_bus_error_free</code>.</p><p><code class="function">sd_bus_error_set</code> will return an | |
98 | errno-like negative value returned based on parameter | |
99 | <em class="parameter"><code>name</code></em> (see | |
5eef597e | 100 | <a href="http://man7.org/linux/man-pages/man3/errno.3.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>). |
60f067b4 JS |
101 | Various well-known D-Bus errors are converted to specific values, |
102 | and the remaining ones to <code class="constant">-ENXIO</code>. Well-known | |
103 | D-Bus error names are available as constants | |
104 | <code class="constant">SD_BUS_ERROR_FAILED</code>, etc., listed above. If | |
105 | <em class="parameter"><code>name</code></em> is <code class="constant">NULL</code>, it is | |
5eef597e | 106 | assumed that no error occurred, and 0 is returned. This means that |
60f067b4 JS |
107 | this function may be conveniently used in a |
108 | <code class="function">return</code> statement.</p><p>If <em class="parameter"><code>e</code></em> is not | |
109 | <code class="constant">NULL</code>, <em class="structfield"><code>name</code></em> and | |
110 | <em class="structfield"><code>message</code></em> in the | |
111 | <span class="structname">sd_bus_error</span> structure | |
112 | <em class="parameter"><code>e</code></em> points at will be filled in. As described above, | |
113 | <em class="parameter"><code>name</code></em> may be <code class="constant">NULL</code>, | |
114 | which is treated as no error. Parameter | |
115 | <em class="parameter"><code>message</code></em> may also be | |
116 | <code class="constant">NULL</code>, in which case no message is specified. | |
117 | <code class="function">sd_bus_error_set</code> will make internal copies of | |
118 | specified strings.</p><p><code class="function">sd_bus_error_setf</code> is similar to | |
119 | <code class="function">sd_bus_error_set</code>, but takes a | |
5eef597e | 120 | <a href="http://man7.org/linux/man-pages/man3/printf.3.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a> |
60f067b4 JS |
121 | format string and corresponding arguments to generate |
122 | <span class="structname">message</span>.</p><p><code class="function">sd_bus_error_set_const</code> is similar to | |
123 | <code class="function">sd_bus_error_set</code>, but string parameters are | |
124 | not copied internally, and must remain valid for the lifetime of | |
125 | <em class="parameter"><code>e</code></em>.</p><p><code class="function">sd_bus_error_set_errno</code> will set | |
126 | <em class="structfield"><code>name</code></em> based on an errno-like value. | |
127 | <a href="strerror.html"><span class="citerefentry"><span class="refentrytitle">strerror</span>(3)</span></a> | |
128 | will be used to set <em class="structfield"><code>message</code></em>. Well-known | |
129 | D-Bus error names will be used for <em class="structfield"><code>name</code></em> | |
130 | if available, otherwise a name in the | |
131 | "<code class="literal">System.Error</code>" namespace will be generated. | |
132 | </p><p><code class="function">sd_bus_error_set_errnof</code> is similar to | |
133 | <code class="function">sd_bus_error_set_errno</code>, but in addition to | |
134 | <em class="parameter"><code>name</code></em>, takes a | |
5eef597e | 135 | <a href="http://man7.org/linux/man-pages/man3/printf.3.html"><span class="citerefentry"><span class="refentrytitle">printf</span>(3)</span></a> |
60f067b4 JS |
136 | format and corresponding arguments. |
137 | <em class="structfield"><code>name</code></em> will be generated from | |
5eef597e | 138 | <em class="parameter"><code>format</code></em> and the arguments.</p><p><code class="function">sd_bus_error_get_errno</code> will convert |
60f067b4 JS |
139 | <span class="structname">e->name</span> to an errno-like value using the |
140 | same rules as <code class="function">sd_bus_error_set</code>. If | |
141 | <em class="parameter"><code>e</code></em> is <code class="constant">NULL</code>, 0 will be | |
142 | returned.</p><p><code class="function">sd_bus_error_copy</code> will initialize | |
143 | <em class="parameter"><code>dst</code></em> using the values in | |
144 | <em class="parameter"><code>e</code></em>. If the strings in | |
145 | <em class="parameter"><code>e</code></em> were set using | |
146 | <code class="function">sd_bus_set_error_const</code>, they will be shared. | |
147 | Otherwise, they will be copied.</p><p><code class="function">sd_bus_error_is_set</code> will return | |
148 | <code class="constant">true</code> if <em class="parameter"><code>e</code></em> is | |
149 | non-<code class="constant">NULL</code> and an error has been set, | |
150 | <code class="constant">false</code> otherwise.</p><p><code class="function">sd_bus_error_has_name</code> will return true | |
151 | if <em class="parameter"><code>e</code></em> is non-<code class="constant">NULL</code> and | |
152 | an error with the same <em class="parameter"><code>name</code></em> has been set, | |
153 | <code class="constant">false</code> otherwise.</p><p><code class="function">sd_bus_error_free</code> will destroy resources | |
154 | held by <em class="parameter"><code>e</code></em>. The parameter itself will not | |
155 | be deallocated, and must be | |
5eef597e | 156 | <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>d |
f47781d8 | 157 | by the caller if necessary.</p></div><div class="refsect1"><a name="idm139886277226800"></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>, |
60f067b4 JS |
158 | <code class="function">sd_bus_error_setf</code>, |
159 | <code class="function">sd_bus_error_set_const</code>, when successful, | |
160 | return the negative errno value corresponding to the | |
161 | <em class="parameter"><code>name</code></em> parameter. Functions | |
162 | <code class="function">sd_bus_error_set_errno</code> and | |
163 | <code class="function">sd_bus_error_set_errnof</code>, when successful, | |
164 | return the value of the <em class="parameter"><code>errno</code></em> parameter. If | |
165 | an error occurs, one of the negative error values listed below | |
166 | will be returned.</p><p><code class="function">sd_bus_error_get_errno</code> returns | |
167 | <code class="constant">false</code> when <em class="parameter"><code>e</code></em> is | |
168 | <code class="constant">NULL</code>, and a positive errno value mapped from | |
169 | <em class="parameter"><code>e->name</code></em> otherwise.</p><p><code class="function">sd_bus_error_copy</code> returns 0 or a | |
170 | positive integer on success, and one of the negative error values | |
171 | listed below otherwise.</p><p><code class="function">sd_bus_error_is_set</code> returns | |
172 | <code class="constant">true</code> when <em class="parameter"><code>e</code></em> and | |
173 | <em class="parameter"><code>e->name</code></em> are non-<code class="constant">NULL</code>, | |
174 | <code class="constant">false</code> otherwise.</p><p><code class="function">sd_bus_error_has_name</code> returns | |
175 | <code class="constant">true</code> when <em class="parameter"><code>e</code></em> is | |
176 | non-<code class="constant">NULL</code> and <em class="parameter"><code>e->name</code></em> | |
177 | is equal to <em class="parameter"><code>name</code></em>, | |
f47781d8 | 178 | <code class="constant">false</code> otherwise.</p></div><div class="refsect1"><a name="idm139886277210080"></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 |
60f067b4 | 179 | counted. Users should destroy resources held by it by calling |
f47781d8 | 180 | <code class="function">sd_bus_error_free</code>.</p></div><div class="refsect1"><a name="idm139886277207936"></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 |
60f067b4 | 181 | <span class="structname">sd_bus_error</span> structure when one the |
f47781d8 | 182 | 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="idm139886277203200"></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 |
60f067b4 JS |
183 | described here are available as a shared library, which can be |
184 | compiled and linked to with the | |
5eef597e | 185 | <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> |
f47781d8 | 186 | file.</p></div><div class="refsect1"><a name="idm139886277200016"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p> |
60f067b4 JS |
187 | <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>, |
188 | <a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>, | |
5eef597e | 189 | <a href="http://man7.org/linux/man-pages/man3/errno.3.html"><span class="citerefentry"><span class="refentrytitle">errno</span>(3)</span></a>, |
60f067b4 JS |
190 | <a href="strerror.html"><span class="citerefentry"><span class="refentrytitle">strerror</span>(3)</span></a> |
191 | </p></div></div></body></html> |