man/sd_bus_error.xml

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