man/sd_bus_error.xml

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