sd_bus_error_set_errno.html 17.9 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<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>·
22
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</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 &lt;systemd/sd-bus.h&gt;</pre><pre class="funcsynopsisinfo">typedef struct {
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
        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>
88
    </p></div><div class="refsect1"><a name="idm214180451616"></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 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
    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="errno.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 occured, 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="printf.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="printf.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> is will convert
    <span class="structname">e-&gt;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="free.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="idm214179308512"></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 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177
    <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-&gt;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-&gt;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-&gt;name</code></em>
    is equal to <em class="parameter"><code>name</code></em>,
178
    <code class="constant">false</code> otherwise.</p></div><div class="refsect1"><a name="idm214180287856"></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="idm214180285584"></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="varname">-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="varname">-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="idm214180280672"></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 184 185
    described here are available as a shared library, which can be
    compiled and linked to with the
    <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
186
    file.</p></div><div class="refsect1"><a name="idm214180277504"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
187 188 189 190 191
      <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="errno.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>