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>
11 background-color: #c60f0f;
15 h1:hover
> a.headerlink, h2:hover
> a.headerlink, h3:hover
> a.headerlink, dt:hover
> a.headerlink {
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>·
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 {
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>
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>
33 <code class=
"constant">SD_BUS_ERROR_NO_MEMORY
</code>
35 <code class=
"constant">SD_BUS_ERROR_SERVICE_UNKNOWN
</code>
37 <code class=
"constant">SD_BUS_ERROR_NAME_HAS_NO_OWNER
</code>
39 <code class=
"constant">SD_BUS_ERROR_NO_REPLY
</code>
41 <code class=
"constant">SD_BUS_ERROR_IO_ERROR
</code>
43 <code class=
"constant">SD_BUS_ERROR_BAD_ADDRESS
</code>
45 <code class=
"constant">SD_BUS_ERROR_NOT_SUPPORTED
</code>
47 <code class=
"constant">SD_BUS_ERROR_LIMITS_EXCEEDED
</code>
49 <code class=
"constant">SD_BUS_ERROR_ACCESS_DENIED
</code>
51 <code class=
"constant">SD_BUS_ERROR_AUTH_FAILED
</code>
53 <code class=
"constant">SD_BUS_ERROR_NO_SERVER
</code>
55 <code class=
"constant">SD_BUS_ERROR_TIMEOUT
</code>
57 <code class=
"constant">SD_BUS_ERROR_NO_NETWORK
</code>
59 <code class=
"constant">SD_BUS_ERROR_ADDRESS_IN_USE
</code>
61 <code class=
"constant">SD_BUS_ERROR_DISCONNECTED
</code>
63 <code class=
"constant">SD_BUS_ERROR_INVALID_ARGS
</code>
65 <code class=
"constant">SD_BUS_ERROR_FILE_NOT_FOUND
</code>
67 <code class=
"constant">SD_BUS_ERROR_FILE_EXISTS
</code>
69 <code class=
"constant">SD_BUS_ERROR_UNKNOWN_METHOD
</code>
71 <code class=
"constant">SD_BUS_ERROR_UNKNOWN_OBJECT
</code>
73 <code class=
"constant">SD_BUS_ERROR_UNKNOWN_INTERFACE
</code>
75 <code class=
"constant">SD_BUS_ERROR_UNKNOWN_PROPERTY
</code>
77 <code class=
"constant">SD_BUS_ERROR_PROPERTY_READ_ONLY
</code>
79 <code class=
"constant">SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN
</code>
81 <code class=
"constant">SD_BUS_ERROR_INVALID_SIGNATURE
</code>
83 <code class=
"constant">SD_BUS_ERROR_INCONSISTENT_MESSAGE
</code>
85 <code class=
"constant">SD_BUS_ERROR_MATCH_RULE_NOT_FOUND
</code>
87 <code class=
"constant">SD_BUS_ERROR_MATCH_RULE_INVALID
</code>
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
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
100 <a href=
"http://man7.org/linux/man-pages/man3/errno.3.html"><span class=
"citerefentry"><span class=
"refentrytitle">errno
</span>(
3)
</span></a>).
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
106 assumed that no error occurred, and
0 is returned. This means that
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
120 <a href=
"http://man7.org/linux/man-pages/man3/printf.3.html"><span class=
"citerefentry"><span class=
"refentrytitle">printf
</span>(
3)
</span></a>
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
135 <a href=
"http://man7.org/linux/man-pages/man3/printf.3.html"><span class=
"citerefentry"><span class=
"refentrytitle">printf
</span>(
3)
</span></a>
136 format and corresponding arguments.
137 <em class=
"structfield"><code>name
</code></em> will be generated from
138 <em class=
"parameter"><code>format
</code></em> and the arguments.
</p><p><code class=
"function">sd_bus_error_get_errno
</code> will convert
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
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
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>,
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>,
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
179 counted. Users should destroy resources held by it by calling
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
181 <span class=
"structname">sd_bus_error
</span> structure when one the
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
183 described here are available as a shared library, which can be
184 compiled and linked to with the
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>
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>
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>,
189 <a href=
"http://man7.org/linux/man-pages/man3/errno.3.html"><span class=
"citerefentry"><span class=
"refentrytitle">errno
</span>(
3)
</span></a>,
190 <a href=
"strerror.html"><span class=
"citerefentry"><span class=
"refentrytitle">strerror
</span>(
3)
</span></a>
191 </p></div></div></body></html>