man/sd_bus_error_has_name.html

   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>·
  22   <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 217</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         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>
  88     </p></div><div class="refsect1"><a name="idm214168488864"></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-&gt;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="idm214168446224"></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-&gt;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-&gt;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-&gt;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="idm214168429504"></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="idm214168427360"></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="idm214168422624"></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="idm214168419440"></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>