man/sd_bus_error.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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">
  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>libsystemd-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><structname>sd_bus_error</structname> structure carries
 235     information for a <filename>libsystemd-bus</filename> error.
 236     Functions described below can be used to set and query fields in
 237     this structure. Field <structfield>name</structfield> 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><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 is
 255     assumed that no error occured, 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> will be filled-in in the
 262     <structname>sd_bus_error</structname> structure
 263     <parameter>e</parameter> points at. 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><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><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> is will convert
 300     <structname>e->name</structname> to an errno-like value
 301     using the same rules as <function>sd_bus_error_set</function>.
 302     </para>
 303
 304     <para><function>sd_bus_error_copy</function> will initialize
 305     <parameter>dst</parameter> using the values in
 306     <parameter>e</parameter>. If the strings in
 307     <parameter>e</parameter> were set using
 308     <function>sd_bus_set_error_const</function>, they will be shared.
 309     Otherwie they wil be copied.</para>
 310
 311     <para><function>sd_bus_error_is_set</function> will return
 312     <constant>true</constant> if <parameter>e</parameter> is
 313     non-<constant>NULL</constant> and an error has been set,
 314     <constant>false</constant> otherwise.</para>
 315
 316     <para><function>sd_bus_error_has_name</function> will return true
 317     if <parameter>e</parameter> is non-<constant>NULL</constant> and
 318     an error with the same <parameter>name</parameter> has been set,
 319     <constant>false</constant> otherwise.</para>
 320
 321     <para><function>sd_bus_error_free</function> will destroy resources
 322     held by <parameter>e</parameter>. The parameter itself will not
 323     be deallocated, and must be
 324     <citerefentry><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
 325     by the caller if necessary.</para>
 326   </refsect1>
 327
 328   <refsect1>
 329     <title>Return Value</title>
 330
 331     <para>Functions <function>sd_bus_error_set</function>,
 332     <function>sd_bus_error_setf</function>,
 333     <function>sd_bus_error_set_const</function>, when successful,
 334     return the negative errno value corresponding to the
 335     <parameter>name</parameter> parameter. Functions
 336     <function>sd_bus_error_set_errno</function> and
 337     <function>sd_bus_error_set_errnof</function>, when successful,
 338     return the value of the <parameter>errno</parameter> parameter. If
 339     an error occurs, one of the negative error values listed below
 340     will be returned.</para>
 341
 342     <para><function>sd_bus_error_get_errno</function> returns
 343     <constant>false</constant> when <parameter>e</parameter> is
 344     <constant>NULL</constant>, and a positive errno value mapped from
 345     <parameter>e->name</parameter> otherwise.</para>
 346
 347     <para><function>sd_bus_error_copy</function> returns 0 or a
 348     positive integer on success, and one of the negative error values
 349     listed below otherwise.</para>
 350
 351     <para><function>sd_bus_error_is_set</function> returns
 352     <constant>true</constant> when <parameter>e</parameter> and
 353     <parameter>e->name</parameter> are non-<constant>NULL</constant>,
 354     <constant>false</constant> otherwise.</para>
 355
 356     <para><function>sd_bus_error_has_name</function> returns
 357     <constant>true</constant> when <parameter>e</parameter> is
 358     non-<constant>NULL</constant> and <parameter>e->name</parameter>
 359     is equal to <parameter>name</parameter>,
 360     <constant>false</constant> otherwise.</para>
 361   </refsect1>
 362
 363   <refsect1>
 364     <title>Reference ownership</title>
 365     <para><structname>sd_bus_error</structname> is not reference
 366     counted. Users should destroy resources held by it by calling
 367     <function>sd_bus_error_free</function>.</para>
 368   </refsect1>
 369
 370   <refsect1>
 371     <title>Errors</title>
 372
 373     <para>Returned errors may indicate the following problems:</para>
 374
 375     <variablelist>
 376
 377       <varlistentry>
 378         <term><varname>-EINVAL</varname></term>
 379
 380         <listitem><para>Error was already set in
 381         <structname>sd_bus_error</structname> structure when one the
 382         error-setting functions was called.</para></listitem>
 383       </varlistentry>
 384
 385       <varlistentry>
 386         <term><varname>-ENOMEM</varname></term>
 387
 388         <listitem><para>Memory allocation failed.</para></listitem>
 389       </varlistentry>
 390     </variablelist>
 391   </refsect1>
 392
 393   <refsect1>
 394     <title>Notes</title>
 395
 396     <para><function>sd_bus_set_error()</function> and other functions
 397     described here are available as a shared library, which can be
 398     compiled and linked to with the
 399     <constant>libsystemd-bus</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 400     file.</para>
 401   </refsect1>
 402
 403   <refsect1>
 404     <title>See Also</title>
 405
 406     <para>
 407       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 408       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 409       <citerefentry><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 410       <citerefentry><refentrytitle>strerror</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 411     </para>
 412   </refsect1>
 413
 414 </refentry>