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