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