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