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">
  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_MAKE_CONST</refname>
  48     <refname>SD_BUS_ERROR_NULL</refname>
  49     <refname>sd_bus_error_free</refname>
  50     <refname>sd_bus_error_set</refname>
  51     <refname>sd_bus_error_setf</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_set_errnofv</refname>
  56     <refname>sd_bus_error_get_errno</refname>
  57     <refname>sd_bus_error_copy</refname>
  58     <refname>sd_bus_error_is_set</refname>
  59     <refname>sd_bus_error_has_name</refname>
  60
  61     <refpurpose>sd-bus error handling</refpurpose>
  62   </refnamediv>
  63
  64   <refsynopsisdiv>
  65     <funcsynopsis>
  66       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  67
  68       <funcsynopsisinfo>typedef struct {
  69         const char *name;
  70         const char *message;
  71         …
  72 } sd_bus_error;</funcsynopsisinfo>
  73
  74       <para>
  75         <constant>SD_BUS_ERROR_MAKE_CONST(<replaceable>name</replaceable>, <replaceable>message</replaceable>)</constant>
  76       </para>
  77       <para>
  78         <constant>SD_BUS_ERROR_NULL</constant>
  79       </para>
  80
  81       <funcprototype>
  82         <funcdef>void <function>sd_bus_error_free</function></funcdef>
  83         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
  84       </funcprototype>
  85
  86       <funcprototype>
  87         <funcdef>int <function>sd_bus_error_set</function></funcdef>
  88         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
  89         <paramdef>const char *<parameter>name</parameter></paramdef>
  90         <paramdef>const char *<parameter>message</parameter></paramdef>
  91       </funcprototype>
  92
  93       <funcprototype>
  94         <funcdef>int <function>sd_bus_error_setf</function></funcdef>
  95         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
  96         <paramdef>const char *<parameter>name</parameter></paramdef>
  97         <paramdef>const char *<parameter>format</parameter></paramdef>
  98         <paramdef>…</paramdef>
  99       </funcprototype>
 100
 101       <funcprototype>
 102         <funcdef>int <function>sd_bus_error_set_const</function></funcdef>
 103         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
 104         <paramdef>const char *<parameter>name</parameter></paramdef>
 105         <paramdef>const char *<parameter>message</parameter></paramdef>
 106       </funcprototype>
 107
 108       <funcprototype>
 109         <funcdef>int <function>sd_bus_error_set_errno</function></funcdef>
 110         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
 111         <paramdef>int <parameter>error</parameter></paramdef>
 112       </funcprototype>
 113
 114       <funcprototype>
 115         <funcdef>int <function>sd_bus_error_set_errnof</function></funcdef>
 116         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
 117         <paramdef>int <parameter>error</parameter></paramdef>
 118         <paramdef>const char *<parameter>format</parameter></paramdef>
 119         <paramdef>…</paramdef>
 120       </funcprototype>
 121
 122       <funcprototype>
 123         <funcdef>int <function>sd_bus_error_set_errnofv</function></funcdef>
 124         <paramdef>sd_bus_error *<parameter>e</parameter></paramdef>
 125         <paramdef>int <parameter>error</parameter></paramdef>
 126         <paramdef>const char *<parameter>format</parameter></paramdef>
 127         <paramdef>va_list ap</paramdef>
 128       </funcprototype>
 129
 130       <funcprototype>
 131         <funcdef>int <function>sd_bus_error_get_errno</function></funcdef>
 132         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
 133       </funcprototype>
 134
 135       <funcprototype>
 136         <funcdef>int <function>sd_bus_error_copy</function></funcdef>
 137         <paramdef>sd_bus_error *<parameter>dst</parameter></paramdef>
 138         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
 139       </funcprototype>
 140
 141       <funcprototype>
 142         <funcdef>int <function>sd_bus_error_is_set</function></funcdef>
 143         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
 144       </funcprototype>
 145
 146       <funcprototype>
 147         <funcdef>int <function>sd_bus_error_has_name</function></funcdef>
 148         <paramdef>const sd_bus_error *<parameter>e</parameter></paramdef>
 149         <paramdef>const char *<parameter>name</parameter></paramdef>
 150       </funcprototype>
 151     </funcsynopsis>
 152
 153   </refsynopsisdiv>
 154
 155   <refsect1>
 156     <title>Description</title>
 157
 158     <para>The <structname>sd_bus_error</structname> structure carries
 159     information about a D-Bus error condition. The functions described
 160     below may be used to set and query fields in this structure. The
 161     <structfield>name</structfield> field contains a short identifier
 162     of an error. It should follow the rules for error names described
 163     in the D-Bus specification, subsection <ulink
 164     url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
 165     Names</ulink>. A number of common, standardized error names are
 166     described in
 167     <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 168     but additional domain-specific errors may be defined by
 169     applications. The <structfield>message</structfield> field usually
 170     contains a human-readable string describing the details, but might
 171     be NULL. An unset <structname>sd_bus_error</structname> structure
 172     should have both fields initialized to NULL. Set an error
 173     structure to <constant>SD_BUS_ERROR_NULL</constant> in order to
 174     reset both fields to NULL. When no longer necessary, resources
 175     held by the <structname>sd_bus_error</structname>structure should
 176     be destroyed with <function>sd_bus_error_free()</function>.</para>
 177
 178     <para><function>sd_bus_error_set()</function> sets an error
 179     structure to the specified name and message strings. The strings
 180     will be copied into internal, newly allocated memory. It is
 181     essential to free the error structure again when it is not
 182     required anymore (see above). The function will return an
 183     <varname>errno</varname>-like negative value (see <citerefentry
 184     project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
 185     determined from the specified error name.  Various well-known
 186     D-Bus errors are converted to well-known <varname>errno</varname>
 187     counterparts, and the other ones to <constant>-EIO</constant>. See
 188     <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 189     for a list of well-known error names. Additional error mappings
 190     may be defined with
 191     <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>. If
 192     <parameter>e</parameter> is NULL, no error structure is initialized,
 193     but the error is still converted into an
 194     <varname>errno</varname>-style error. If
 195     <parameter>name</parameter> is <constant>NULL</constant>, it is
 196     assumed that no error occurred, and 0 is returned. This means that
 197     this function may be conveniently used in a
 198     <function>return</function> statement. If
 199     <parameter>message</parameter> is NULL, no message is set. This
 200     call can fail if no memory may be allocated for the name and
 201     message strings, in which case an
 202     <constant>SD_BUS_ERROR_NO_MEMORY</constant> error might be set
 203     instead and -ENOMEM be returned. Do not use this call on error
 204     structures that are already initialized. If you intend to reuse an
 205     error structure, free the old data stored in it with
 206     <function>sd_bus_error_free()</function> first.</para>
 207
 208     <para><function>sd_bus_error_setf()</function> is similar to
 209     <function>sd_bus_error_set()</function>, but takes a <citerefentry
 210     project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 211     format string and corresponding arguments to generate the
 212     <structfield>message</structfield> field.</para>
 213
 214     <para><function>sd_bus_error_set_const()</function> is similar to
 215     <function>sd_bus_error_set()</function>, but the string parameters
 216     are not copied internally, and must hence remain constant and
 217     valid for the lifetime of <parameter>e</parameter>. Use this call
 218     to avoid memory allocations when setting error structures. Since
 219     this call does not allocate memory, it will not fail with an
 220     out-of-memory condition as
 221     <function>sd_bus_error_set()</function> can, as described
 222     above. Alternatively, the
 223     <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used
 224     to generate a literal, constant bus error structure
 225     on-the-fly.</para>
 226
 227     <para><function>sd_bus_error_set_errno()</function> will set
 228     <structfield>name</structfield> from an
 229     <varname>errno</varname>-like value that is converted to a D-Bus
 230     error. <citerefentry
 231     project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 232     will be used to set <structfield>message</structfield>. Well-known
 233     D-Bus error names will be used for <structfield>name</structfield>
 234     if applicable, otherwise a name in the
 235     <literal>System.Error.</literal> namespace will be generated. The
 236     sign of the specified error number is ignored. The absolute value
 237     is used implicitly. The call always returns a negative value, for
 238     convenient usage in <function>return</function> statements. This
 239     call might fail due to lack of memory, in which case an
 240     <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead,
 241     and -ENOMEM is returned.</para>
 242
 243     <para><function>sd_bus_error_set_errnof()</function> is similar to
 244     <function>sd_bus_error_set_errno()</function>, but in addition to
 245     <parameter>error</parameter>, takes a <citerefentry
 246     project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 247     format string and corresponding arguments.  The
 248     <structfield>message</structfield> field will be generated from
 249     <parameter>format</parameter> and the arguments.</para>
 250
 251     <para><function>sd_bus_error_set_errnofv()</function> is similar to
 252     <function>sd_bus_error_set_errnof()</function>, but takes the
 253     format string parameters as <citerefentry
 254     project='man-pages'><refentrytitle>va_arg</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 255     parameter list.</para>
 256
 257     <para><function>sd_bus_error_get_errno()</function> converts the
 258     <structfield>name</structfield> field of an error structure to an
 259     <varname>errno</varname>-like (positive) value using the same
 260     rules as <function>sd_bus_error_set()</function>.  If
 261     <parameter>e</parameter> is <constant>NULL</constant>, 0 will be
 262     returned.</para>
 263
 264     <para><function>sd_bus_error_copy()</function> will initialize
 265     <parameter>dst</parameter> using the values in
 266     <parameter>e</parameter>. If the strings in
 267     <parameter>e</parameter> were set using
 268     <function>sd_bus_set_error_const()</function>, they will be shared.
 269     Otherwise, they will be copied. Returns a converted
 270     <varname>errno</varname>-like, negative error code.</para>
 271
 272     <para><function>sd_bus_error_is_set()</function> will return a
 273     non-zero value if <parameter>e</parameter> is
 274     non-<constant>NULL</constant> and an error has been set,
 275     <constant>false</constant> otherwise.</para>
 276
 277     <para><function>sd_bus_error_has_name()</function> will return a
 278     non-zero value if <parameter>e</parameter> is
 279     non-<constant>NULL</constant> and an error with the same
 280     <parameter>name</parameter> has been set,
 281     <constant>false</constant> otherwise.</para>
 282
 283     <para><function>sd_bus_error_free()</function> will destroy
 284     resources held by <parameter>e</parameter>. The parameter itself
 285     will not be deallocated, and must be <citerefentry
 286     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>d
 287     by the caller if necessary. The function may also be called safely
 288     on unset errors (error structures with both fields set to NULL),
 289     in which case it performs no operation. This call will reset the
 290     error structure after freeing the data, so that all fields are set
 291     to NULL. The structure may be reused afterwards.</para>
 292   </refsect1>
 293
 294   <refsect1>
 295     <title>Return Value</title>
 296
 297     <para>The functions <function>sd_bus_error_set()</function>,
 298     <function>sd_bus_error_setf()</function>, and
 299     <function>sd_bus_error_set_const()</function>, when successful,
 300     return the negative errno value corresponding to the
 301     <parameter>name</parameter> parameter. The functions
 302     <function>sd_bus_error_set_errno()</function>,
 303     <function>sd_bus_error_set_errnof()</function> and
 304     <function>sd_bus_error_set_errnofv()</function>, when successful,
 305     return the negative value of the <parameter>error</parameter>
 306     parameter. If an error occurs, one of the negative error values
 307     listed below will be returned.</para>
 308
 309     <para><function>sd_bus_error_get_errno()</function> returns
 310     <constant>false</constant> when <parameter>e</parameter> is
 311     <constant>NULL</constant>, and a positive errno value mapped from
 312     <parameter>e-&gt;name</parameter> otherwise.</para>
 313
 314     <para><function>sd_bus_error_copy()</function> returns 0 or a
 315     positive integer on success, and a negative error value converted
 316     from the error name otherwise.</para>
 317
 318     <para><function>sd_bus_error_is_set()</function> returns a
 319     non-zero value when <parameter>e</parameter> and the
 320     <structfield>name</structfield> field are
 321     non-<constant>NULL</constant>, zero otherwise.</para>
 322
 323     <para><function>sd_bus_error_has_name()</function> returns a
 324     non-zero value when <parameter>e</parameter> is
 325     non-<constant>NULL</constant> and the
 326     <structfield>name</structfield> field is equal to
 327     <parameter>name</parameter>, zero otherwise.</para>
 328   </refsect1>
 329
 330   <refsect1>
 331     <title>Reference ownership</title>
 332     <para><structname>sd_bus_error</structname> is not reference
 333     counted. Users should destroy resources held by it by calling
 334     <function>sd_bus_error_free()</function>. Usually, error structures
 335     are allocated on the stack or passed in as function parameters,
 336     but they may also be allocated dynamically, in which case it is
 337     the duty of the caller to <citerefentry
 338     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 339     the memory held by the structure itself after freeing its contents
 340     with <function>sd_bus_error_free()</function>.</para>
 341   </refsect1>
 342
 343   <refsect1>
 344     <title>Errors</title>
 345
 346     <para>Returned errors may indicate the following problems:</para>
 347
 348     <variablelist>
 349
 350       <varlistentry>
 351         <term><constant>-EINVAL</constant></term>
 352
 353         <listitem><para>Error was already set in
 354         <structname>sd_bus_error</structname> structure when one the
 355         error-setting functions was called.</para></listitem>
 356       </varlistentry>
 357
 358       <varlistentry>
 359         <term><constant>-ENOMEM</constant></term>
 360
 361         <listitem><para>Memory allocation failed.</para></listitem>
 362       </varlistentry>
 363     </variablelist>
 364   </refsect1>
 365
 366   <refsect1>
 367     <title>Notes</title>
 368
 369     <para><function>sd_bus_set_error()</function> and other functions
 370     described here are available as a shared library, which can be
 371     compiled and linked to with the
 372     <constant>libelogind</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 373     file.</para>
 374   </refsect1>
 375
 376   <refsect1>
 377     <title>See Also</title>
 378
 379     <para>
 380       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 381       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 382       <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 383       <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 384       <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 385       <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 386     </para>
 387   </refsect1>
 388
 389 </refentry>