man/sd_bus_error.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2014 Zbigniew Jędrzejewski-Szmek
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="sd_bus_error">
  28
  29   <refentryinfo>
  30     <title>sd_bus_error</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>A monkey with a typewriter</contrib>
  36         <firstname>Zbigniew</firstname>
  37         <surname>Jędrzejewski-Szmek</surname>
  38         <email>zbyszek@in.waw.pl</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>sd_bus_error</refentrytitle>
  45     <manvolnum>3</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>sd_bus_error</refname>
  50     <refname>sd_bus_error_free</refname>
  51     <refname>sd_bus_error_set</refname>
  52     <refname>sd_bus_error_set_const</refname>
  53     <refname>sd_bus_error_set_errno</refname>
  54     <refname>sd_bus_error_set_errnof</refname>
  55     <refname>sd_bus_error_get_errno</refname>
  56     <refname>sd_bus_error_copy</refname>
  57     <refname>sd_bus_error_is_set</refname>
  58     <refname>sd_bus_error_has_name</refname>
  59
  60     <refpurpose>sd-bus error handling</refpurpose>
  61   </refnamediv>
  62
  63   <refsynopsisdiv>
  64     <funcsynopsis>
  65       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  66
  67       <funcsynopsisinfo>typedef struct {
  68         const char *name;
  69         const char *message;
  70         ...
  71 } sd_bus_error;</funcsynopsisinfo>
  72
  73       <para>
  74         <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant>
  75       </para>
  76       <para>
  77         <constant>SD_BUS_ERROR_NULL</constant>
  78       </para>
  79
  80       <funcprototype>
  81         <funcdef>int <function>sd_bus_error_free</function></funcdef>
  82         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
  83       </funcprototype>
  84
  85       <funcprototype>
  86         <funcdef>int <function>sd_bus_error_set</function></funcdef>
  87         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
  88         <paramdef>const char *<parameter>name</parameter></paramdef>
  89         <paramdef>const char *<parameter>message</parameter></paramdef>
  90       </funcprototype>
  91
  92       <funcprototype>
  93         <funcdef>int <function>sd_bus_error_setf</function></funcdef>
  94         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
  95         <paramdef>const char *<parameter>name</parameter></paramdef>
  96         <paramdef>const char *<parameter>format</parameter></paramdef>
  97         <paramdef>...</paramdef>
  98       </funcprototype>
  99
 100       <funcprototype>
 101         <funcdef>int <function>sd_bus_error_set_const</function></funcdef>
 102         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
 103         <paramdef>const char *<parameter>name</parameter></paramdef>
 104         <paramdef>const char *<parameter>message</parameter></paramdef>
 105       </funcprototype>
 106
 107       <funcprototype>
 108         <funcdef>int <function>sd_bus_error_set_errno</function></funcdef>
 109         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
 110         <paramdef>int <parameter>error</parameter></paramdef>
 111       </funcprototype>
 112
 113       <funcprototype>
 114         <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef>
 115         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
 116         <paramdef>int <parameter>error</parameter></paramdef>
 117         <paramdef>const char *<parameter>format</parameter></paramdef>
 118         <paramdef>...</paramdef>
 119       </funcprototype>
 120
 121       <funcprototype>
 122         <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
 123         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
 124       </funcprototype>
 125
 126       <funcprototype>
 127         <funcdef>int <function>sd_bus_error_copy</function></funcdef>
 128         <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef>
 129         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
 130       </funcprototype>
 131
 132       <funcprototype>
 133         <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
 134         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
 135       </funcprototype>
 136
 137       <funcprototype>
 138         <funcdef>int <function>sd_bus_error_has_name</function></funcdef>
 139         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
 140         <paramdef>const char *<parameter>name</parameter></paramdef>
 141       </funcprototype>
 142     </funcsynopsis>
 143
 144     <para>
 145       <constant>SD_BUS_ERROR_FAILED</constant>
 146     </para>
 147     <para>
 148       <constant>SD_BUS_ERROR_NO_MEMORY</constant>
 149     </para>
 150     <para>
 151       <constant>SD_BUS_ERROR_SERVICE_UNKNOWN</constant>
 152     </para>
 153     <para>
 154       <constant>SD_BUS_ERROR_NAME_HAS_NO_OWNER</constant>
 155     </para>
 156     <para>
 157       <constant>SD_BUS_ERROR_NO_REPLY</constant>
 158     </para>
 159     <para>
 160       <constant>SD_BUS_ERROR_IO_ERROR</constant>
 161     </para>
 162     <para>
 163       <constant>SD_BUS_ERROR_BAD_ADDRESS</constant>
 164     </para>
 165     <para>
 166       <constant>SD_BUS_ERROR_NOT_SUPPORTED</constant>
 167     </para>
 168     <para>
 169       <constant>SD_BUS_ERROR_LIMITS_EXCEEDED</constant>
 170     </para>
 171     <para>
 172       <constant>SD_BUS_ERROR_ACCESS_DENIED</constant>
 173     </para>
 174     <para>
 175       <constant>SD_BUS_ERROR_AUTH_FAILED</constant>
 176     </para>
 177     <para>
 178       <constant>SD_BUS_ERROR_NO_SERVER</constant>
 179     </para>
 180     <para>
 181       <constant>SD_BUS_ERROR_TIMEOUT</constant>
 182     </para>
 183     <para>
 184       <constant>SD_BUS_ERROR_NO_NETWORK</constant>
 185     </para>
 186     <para>
 187       <constant>SD_BUS_ERROR_ADDRESS_IN_USE</constant>
 188     </para>
 189     <para>
 190       <constant>SD_BUS_ERROR_DISCONNECTED</constant>
 191     </para>
 192     <para>
 193       <constant>SD_BUS_ERROR_INVALID_ARGS</constant>
 194     </para>
 195     <para>
 196       <constant>SD_BUS_ERROR_FILE_NOT_FOUND</constant>
 197     </para>
 198     <para>
 199       <constant>SD_BUS_ERROR_FILE_EXISTS</constant>
 200     </para>
 201     <para>
 202       <constant>SD_BUS_ERROR_UNKNOWN_METHOD</constant>
 203     </para>
 204     <para>
 205       <constant>SD_BUS_ERROR_UNKNOWN_OBJECT</constant>
 206     </para>
 207     <para>
 208       <constant>SD_BUS_ERROR_UNKNOWN_INTERFACE</constant>
 209     </para>
 210     <para>
 211       <constant>SD_BUS_ERROR_UNKNOWN_PROPERTY</constant>
 212     </para>
 213     <para>
 214       <constant>SD_BUS_ERROR_PROPERTY_READ_ONLY</constant>
 215     </para>
 216     <para>
 217       <constant>SD_BUS_ERROR_UNIX_PROCESS_ID_UNKNOWN</constant>
 218     </para>
 219     <para>
 220       <constant>SD_BUS_ERROR_INVALID_SIGNATURE</constant>
 221     </para>
 222     <para>
 223       <constant>SD_BUS_ERROR_INCONSISTENT_MESSAGE</constant>
 224     </para>
 225     <para>
 226       <constant>SD_BUS_ERROR_MATCH_RULE_NOT_FOUND</constant>
 227     </para>
 228     <para>
 229       <constant>SD_BUS_ERROR_MATCH_RULE_INVALID</constant>
 230     </para>
 231
 232   </refsynopsisdiv>
 233
 234   <refsect1>
 235     <title>Description</title>
 236
 237     <para>The <structname>sd_bus_error</structname> structure carries
 238     information for a <filename>sd-bus</filename> error. The
 239     functions described below can be used to set and query fields in
 240     this structure. The <structfield>name</structfield> field contains a
 241     short identifier of an error. It should follow the rules for error
 242     names described in the D-Bus specification, subsection <ulink
 243     url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
 244     Names</ulink>. The <structfield>message</structfield> is a human
 245     readable string describing the details. When no longer necessary,
 246     resources held by this structure should be destroyed with
 247     <function>sd_bus_error_free</function>.</para>
 248
 249     <para><function>sd_bus_error_set</function> will return an
 250     errno-like negative value returned based on parameter
 251     <parameter>name</parameter> (see
 252     <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>).
 253     Various well-known D-Bus errors are converted to specific values,
 254     and the remaining ones to <constant>-ENXIO</constant>. Well-known
 255     D-Bus error names are available as constants
 256     <constant>SD_BUS_ERROR_FAILED</constant>, etc., listed above. If
 257     <parameter>name</parameter> is <constant>NULL</constant>, it is
 258     assumed that no error occurred, and 0 is returned. This means that
 259     this function may be conveniently used in a
 260     <function>return</function> statement.</para>
 261
 262     <para>If <parameter>e</parameter> is not
 263     <constant>NULL</constant>, <structfield>name</structfield> and
 264     <structfield>message</structfield> in the
 265     <structname>sd_bus_error</structname> structure
 266     <parameter>e</parameter> points at will be filled in. As described above,
 267     <parameter>name</parameter> may be <constant>NULL</constant>,
 268     which is treated as no error. Parameter
 269     <parameter>message</parameter> may also be
 270     <constant>NULL</constant>, in which case no message is specified.
 271     <function>sd_bus_error_set</function> will make internal copies of
 272     specified strings.</para>
 273
 274     <para><function>sd_bus_error_setf</function> is similar to
 275     <function>sd_bus_error_set</function>, but takes a
 276     <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 277     format string and corresponding arguments to generate
 278     <structname>message</structname>.</para>
 279
 280     <para><function>sd_bus_error_set_const</function> is similar to
 281     <function>sd_bus_error_set</function>, but string parameters are
 282     not copied internally, and must remain valid for the lifetime of
 283     <parameter>e</parameter>.</para>
 284
 285     <para><function>sd_bus_error_set_errno</function> will set
 286     <structfield>name</structfield> based on an errno-like value.
 287     <citerefentry project='die-net'><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 288     will be used to set <structfield>message</structfield>. Well-known
 289     D-Bus error names will be used for <structfield>name</structfield>
 290     if available, otherwise a name in the
 291     <literal>System.Error</literal> namespace will be generated.
 292     </para>
 293
 294     <para><function>sd_bus_error_set_errnof</function> is similar to
 295     <function>sd_bus_error_set_errno</function>, but in addition to
 296     <parameter>name</parameter>, takes a
 297     <citerefentry project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 298     format and corresponding arguments.
 299     <structfield>name</structfield> will be generated from
 300     <parameter>format</parameter> and the arguments.</para>
 301
 302     <para><function>sd_bus_error_get_errno</function> will convert
 303     <structname>e-&gt;name</structname> to an errno-like value using the
 304     same rules as <function>sd_bus_error_set</function>.  If
 305     <parameter>e</parameter> is <constant>NULL</constant>, 0 will be
 306     returned.</para>
 307
 308     <para><function>sd_bus_error_copy</function> will initialize
 309     <parameter>dst</parameter> using the values in
 310     <parameter>e</parameter>. If the strings in
 311     <parameter>e</parameter> were set using
 312     <function>sd_bus_set_error_const</function>, they will be shared.
 313     Otherwise, they will be copied.</para>
 314
 315     <para><function>sd_bus_error_is_set</function> will return
 316     <constant>true</constant> if <parameter>e</parameter> is
 317     non-<constant>NULL</constant> and an error has been set,
 318     <constant>false</constant> otherwise.</para>
 319
 320     <para><function>sd_bus_error_has_name</function> will return true
 321     if <parameter>e</parameter> is non-<constant>NULL</constant> and
 322     an error with the same <parameter>name</parameter> has been set,
 323     <constant>false</constant> otherwise.</para>
 324
 325     <para><function>sd_bus_error_free</function> will destroy resources
 326     held by <parameter>e</parameter>. The parameter itself will not
 327     be deallocated, and must be
 328     <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
 329     by the caller if necessary.</para>
 330   </refsect1>
 331
 332   <refsect1>
 333     <title>Return Value</title>
 334
 335     <para>Functions <function>sd_bus_error_set</function>,
 336     <function>sd_bus_error_setf</function>,
 337     <function>sd_bus_error_set_const</function>, when successful,
 338     return the negative errno value corresponding to the
 339     <parameter>name</parameter> parameter. Functions
 340     <function>sd_bus_error_set_errno</function> and
 341     <function>sd_bus_error_set_errnof</function>, when successful,
 342     return the value of the <parameter>errno</parameter> parameter. If
 343     an error occurs, one of the negative error values listed below
 344     will be returned.</para>
 345
 346     <para><function>sd_bus_error_get_errno</function> returns
 347     <constant>false</constant> when <parameter>e</parameter> is
 348     <constant>NULL</constant>, and a positive errno value mapped from
 349     <parameter>e-&gt;name</parameter> otherwise.</para>
 350
 351     <para><function>sd_bus_error_copy</function> returns 0 or a
 352     positive integer on success, and one of the negative error values
 353     listed below otherwise.</para>
 354
 355     <para><function>sd_bus_error_is_set</function> returns
 356     <constant>true</constant> when <parameter>e</parameter> and
 357     <parameter>e-&gt;name</parameter> are non-<constant>NULL</constant>,
 358     <constant>false</constant> otherwise.</para>
 359
 360     <para><function>sd_bus_error_has_name</function> returns
 361     <constant>true</constant> when <parameter>e</parameter> is
 362     non-<constant>NULL</constant> and <parameter>e-&gt;name</parameter>
 363     is equal to <parameter>name</parameter>,
 364     <constant>false</constant> otherwise.</para>
 365   </refsect1>
 366
 367   <refsect1>
 368     <title>Reference ownership</title>
 369     <para><structname>sd_bus_error</structname> is not reference
 370     counted. Users should destroy resources held by it by calling
 371     <function>sd_bus_error_free</function>.</para>
 372   </refsect1>
 373
 374   <refsect1>
 375     <title>Errors</title>
 376
 377     <para>Returned errors may indicate the following problems:</para>
 378
 379     <variablelist>
 380
 381       <varlistentry>
 382         <term><constant>-EINVAL</constant></term>
 383
 384         <listitem><para>Error was already set in
 385         <structname>sd_bus_error</structname> structure when one the
 386         error-setting functions was called.</para></listitem>
 387       </varlistentry>
 388
 389       <varlistentry>
 390         <term><constant>-ENOMEM</constant></term>
 391
 392         <listitem><para>Memory allocation failed.</para></listitem>
 393       </varlistentry>
 394     </variablelist>
 395   </refsect1>
 396
 397   <refsect1>
 398     <title>Notes</title>
 399
 400     <para><function>sd_bus_set_error()</function> and other functions
 401     described here are available as a shared library, which can be
 402     compiled and linked to with the
 403     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 404     file.</para>
 405   </refsect1>
 406
 407   <refsect1>
 408     <title>See Also</title>
 409
 410     <para>
 411       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 412       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 413       <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 414       <citerefentry project='die-net'><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 415     </para>
 416   </refsect1>
 417
 418 </refentry>