mirror of
https://git.proxmox.com/git/systemd
synced 2025-11-04 11:07:20 +00:00
192 lines
18 KiB
HTML
192 lines
18 KiB
HTML
<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>·
|
||
<a href="../libudev/index.html">libudev </a>·
|
||
<a href="../libudev/index.html">gudev </a><span style="float:right">systemd 219</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="idm140307284751792"></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="strerror.html"><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="idm140307284709152"></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="idm140307284692432"></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="idm140307284690288"></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="idm140307284685552"></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="idm140307284682368"></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="strerror.html"><span class="citerefentry"><span class="refentrytitle">strerror</span>(3)</span></a>
|
||
</p></div></div></body></html>
|