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-or-later -->
   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 information about a D-Bus error
 151     condition, or lack thereof. The functions described below may be used to set and query fields in this
 152     structure.
 153     <itemizedlist>
 154       <listitem><para>The <structfield>name</structfield> field contains a short identifier of an error. It
 155       should follow the rules for error names described 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 described in
 158       <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but
 159       additional domain-specific errors may be defined by applications.</para></listitem>
 160
 161       <listitem><para>The <structfield>message</structfield> field usually contains a human-readable string
 162       describing the details, but might be <constant>NULL</constant>.</para></listitem>
 163     </itemizedlist>
 164     An unset <structname>sd_bus_error</structname> structure should have both fields initialized to
 165     <constant>NULL</constant>, and signifies lack of an error, i.e. success. Assign
 166     <constant>SD_BUS_ERROR_NULL</constant> to the structure in order to initialize both fields to
 167     <constant>NULL</constant>. When no longer necessary, resources held by the
 168     <structname>sd_bus_error</structname> structure should be destroyed with
 169     <function>sd_bus_error_free()</function>.</para>
 170
 171     <para><function>sd_bus_error_set()</function> sets an error structure to the specified name and message
 172     strings. The strings will be copied into internal, newly allocated memory. It is essential to free the
 173     contents again when they are not required anymore (see above). Do not use this call on error structures
 174     that have already been set. If you intend to reuse an error structure, free the old data stored in it
 175     with <function>sd_bus_error_free()</function> first.</para>
 176
 177     <para><function>sd_bus_error_set()</function> will return an <varname>errno</varname>-like value (see
 178     <citerefentry
 179     project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
 180     determined from the specified error name <parameter>name</parameter>. If <parameter>name</parameter> is
 181     <constant>NULL</constant>, it is assumed that no error occurred, and <constant>0</constant> is returned.
 182     If <parameter>name</parameter> is nonnull, a negative value is always returned. If
 183     <parameter>e</parameter> is <constant>NULL</constant>, no error structure is initialized, but
 184     <parameter>name</parameter> is still converted into an <varname>errno</varname>-style value.</para>
 185
 186     <para>Various well-known D-Bus errors are converted to well-known <varname>errno</varname> counterparts,
 187     and the other ones to <constant>-EIO</constant>. See
 188     <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry> for a
 189     list of well-known error names. Additional error mappings may be defined with
 190     <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 191     </para>
 192
 193     <para><function>sd_bus_error_set()</function> is designed to be conveniently used in a
 194     <function>return</function> statement. If <parameter>message</parameter> is <constant>NULL</constant>, no
 195     message is set. This call can fail if no memory may be allocated for the name and message strings, in
 196     which case an <constant>SD_BUS_ERROR_NO_MEMORY</constant> error will be set instead and
 197     <constant>-ENOMEM</constant> returned. </para>
 198
 199     <para><function>sd_bus_error_setf()</function> is similar to
 200     <function>sd_bus_error_set()</function>, but takes a <citerefentry
 201     project='man-pages'><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 202     format string and corresponding arguments to generate the
 203     <structfield>message</structfield> field.</para>
 204
 205     <para><function>sd_bus_error_set_const()</function> is similar to
 206     <function>sd_bus_error_set()</function>, but the string parameters are not copied internally, and must
 207     hence remain constant and valid for the lifetime of <parameter>e</parameter>. Use this call to avoid
 208     memory allocations when setting error structures. Since this call does not allocate memory, it will not
 209     fail with an out-of-memory condition as <function>sd_bus_error_set()</function> may, as described
 210     above. Alternatively, the <constant>SD_BUS_ERROR_MAKE_CONST()</constant> macro may be used to generate a
 211     literal, constant bus error structure on-the-fly.</para>
 212
 213     <para><function>sd_bus_error_set_errno()</function> will immediately return <constant>0</constant> if the
 214     specified error parameter <parameter>error</parameter> is <constant>0</constant>. Otherwise, it will set
 215     <structfield>name</structfield> from an <varname>errno</varname>-like value that is converted to a D-Bus
 216     error. <citerefentry
 217     project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry> will
 218     be used to set <structfield>message</structfield>. Well-known D-Bus error names will be used for
 219     <structfield>name</structfield> if applicable, otherwise a name in the <literal>System.Error.</literal>
 220     namespace will be generated. The sign of the specified error number is ignored and the absolute value is
 221     used implicitly. If the specified error <parameter>error</parameter> is non-zero, the call always returns
 222     a negative value, for convenient usage in <function>return</function> statements. This call might fail
 223     due to lack of memory, in which case an <constant>SD_BUS_ERROR_NO_MEMORY</constant> error is set instead,
 224     and <constant>-ENOMEM</constant> 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 <structfield>name</structfield> field of
 241     an error structure to an <varname>errno</varname>-like (positive) value using the same rules as
 242     <function>sd_bus_error_set()</function>.  If <parameter>e</parameter> is <constant>NULL</constant>,
 243     <constant>0</constant> will be returned.</para>
 244
 245     <para><function>sd_bus_error_copy()</function> will initialize <parameter>dst</parameter> using the
 246     values in <parameter>e</parameter>, if <parameter>e</parameter> has been set with an error value before.
 247     Otherwise, it will return immediately. If the strings in <parameter>e</parameter> were set using
 248     <function>sd_bus_error_set_const()</function>, they will be shared. Otherwise, they will be
 249     copied. Before this call, <parameter>dst</parameter> must be unset, i.e. either freshly initialized with
 250     <constant>NULL</constant> or reset using <function>sd_bus_error_free()</function>.</para>
 251
 252     <para><function>sd_bus_error_copy()</function> generally returns <constant>0</constant> or a negative
 253     <varname>errno</varname>-like value based on the input parameter <parameter>e</parameter>:
 254     <constant>0</constant> if it was unset and a negative integer if it was set to some error, similarly to
 255     <function>sd_bus_error_set()</function>. It may however also return an error generated internally, for
 256     example <constant>-ENOMEM</constant> if a memory allocation fails.</para>
 257
 258     <para><function>sd_bus_error_move()</function> is similar to <function>sd_bus_error_copy()</function>,
 259     but will move any error information from <parameter>e</parameter> into <parameter>dst</parameter>,
 260     resetting the former. This function cannot fail, as no new memory is allocated. Note that if
 261     <parameter>e</parameter> is not set, <parameter>dst</parameter> is initialized to
 262     <constant>SD_BUS_ERROR_NULL</constant>. Moreover, if <parameter>dst</parameter> is
 263     <constant>NULL</constant> no operation is executed on it and resources held by <parameter>e</parameter>
 264     are freed and reset. Returns a converted <varname>errno</varname>-like, non-positive error value.</para>
 265
 266     <para><function>sd_bus_error_is_set()</function> will return a
 267     non-zero value if <parameter>e</parameter> is
 268     non-<constant>NULL</constant> and an error has been set,
 269     <constant>false</constant> otherwise.</para>
 270
 271     <para><function>sd_bus_error_has_name()</function> will return a
 272     non-zero value if <parameter>e</parameter> is
 273     non-<constant>NULL</constant> and an error with the same
 274     <parameter>name</parameter> has been set,
 275     <constant>false</constant> otherwise.</para>
 276
 277     <para><function>sd_bus_error_has_names_sentinel()</function> is similar to
 278     <function>sd_bus_error_has_name()</function>, but takes multiple names to check against. The list must be
 279     terminated with <constant>NULL</constant>. <function>sd_bus_error_has_names()</function>
 280     is a macro wrapper around <function>sd_bus_error_has_names_sentinel()</function> that adds the
 281     <constant>NULL</constant> sentinel automatically.</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 <constant>NULL</constant>),
 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 <constant>NULL</constant>. The structure may be reused afterwards.</para>
 292   </refsect1>
 293
 294   <refsect1>
 295     <title>Reference ownership</title>
 296
 297     <para><structname>sd_bus_error</structname> is not reference-counted. Users should destroy resources held
 298     by it by calling <function>sd_bus_error_free()</function>. Usually, error structures are allocated on the
 299     stack or passed in as function parameters, but they may also be allocated dynamically, in which case it
 300     is the duty of the caller to <citerefentry
 301     project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry> the memory
 302     held by the structure itself after freeing its contents with
 303     <function>sd_bus_error_free()</function>.</para>
 304   </refsect1>
 305
 306   <refsect1>
 307     <title>Return Value</title>
 308
 309     <para>The functions <function>sd_bus_error_set()</function>, <function>sd_bus_error_setf()</function>,
 310     and <function>sd_bus_error_set_const()</function> always return <constant>0</constant> when the specified
 311     error value is <constant>NULL</constant>, and a negative errno-like value corresponding to the
 312     <parameter>name</parameter> parameter otherwise. The functions
 313     <function>sd_bus_error_set_errno()</function>, <function>sd_bus_error_set_errnof()</function> and
 314     <function>sd_bus_error_set_errnofv()</function>, return <constant>0</constant> when the specified error
 315     value is <constant>0</constant>, and a negative errno-like value corresponding to the
 316     <parameter>error</parameter> parameter otherwise. If an error occurs internally, one of the negative
 317     error values listed below will be returned. This allows those functions to be conveniently used in a
 318     <constant>return</constant> statement, see the example below.</para>
 319
 320     <para><function>sd_bus_error_get_errno()</function> returns
 321     <constant>false</constant> when <parameter>e</parameter> is
 322     <constant>NULL</constant>, and a positive errno value mapped from
 323     <parameter>e-&gt;name</parameter> otherwise.</para>
 324
 325     <para><function>sd_bus_error_copy()</function> and <function>sd_bus_error_move()</function> return a
 326     negative error value converted from the source error, and zero if the error has not been set.  This
 327     allows those functions to be conveniently used in a <constant>return</constant> statement, see the
 328     example below.</para>
 329
 330     <para><function>sd_bus_error_is_set()</function> returns a
 331     non-zero value when <parameter>e</parameter> and the
 332     <structfield>name</structfield> field are
 333     non-<constant>NULL</constant>, zero otherwise.</para>
 334
 335     <para><function>sd_bus_error_has_name()</function>, <function>sd_bus_error_has_names()</function>, and
 336     <function>sd_bus_error_has_names_sentinel()</function> return a non-zero value when <parameter>e</parameter> is
 337     non-<constant>NULL</constant> and the <structfield>name</structfield> field is equal to one of the given
 338     names, zero otherwise.</para>
 339
 340     <refsect2>
 341       <title>Errors</title>
 342
 343       <para>Return value may indicate the following problems in the invocation of the function itself:</para>
 344
 345       <variablelist>
 346         <varlistentry>
 347           <term><constant>-EINVAL</constant></term>
 348
 349           <listitem><para>Error was already set in the <structname>sd_bus_error</structname> structure when
 350           one the error-setting functions was called.</para></listitem>
 351         </varlistentry>
 352
 353         <varlistentry>
 354           <term><constant>-ENOMEM</constant></term>
 355
 356           <listitem><para>Memory allocation failed.</para></listitem>
 357         </varlistentry>
 358       </variablelist>
 359
 360       <para>On success, <function>sd_bus_error_set()</function>, <function>sd_bus_error_setf()</function>,
 361       <function>sd_bus_error_set_const()</function>, <function>sd_bus_error_set_errno()</function>,
 362       <function>sd_bus_error_set_errnof()</function>, <function>sd_bus_error_set_errnofv()</function>,
 363       <function>sd_bus_error_copy()</function>, and <function>sd_bus_error_move()</function> will return a
 364       negative converted <varname>errno</varname>-style value, or <constant>0</constant> if the error
 365       parameter is <constant>NULL</constant> or unset. D-Bus errors are converted to the integral
 366       <varname>errno</varname>-style value, and the mapping mechanism is extensible, see the discussion
 367       above. This effectively means that almost any negative <varname>errno</varname>-style value can be
 368       returned.</para>
 369     </refsect2>
 370   </refsect1>
 371
 372   <refsect1>
 373     <title>Examples</title>
 374
 375     <example>
 376       <title>Using the negative return value to propagate an error</title>
 377
 378       <programlisting><xi:include href="sd_bus_error-example.c" parse="text" /></programlisting>
 379     </example>
 380   </refsect1>
 381
 382   <xi:include href="libsystemd-pkgconfig.xml" />
 383
 384   <refsect1>
 385     <title>See Also</title>
 386
 387     <para>
 388       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 389       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 390       <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 391       <citerefentry><refentrytitle>sd_bus_error_add_map</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 392       <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 393       <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 394     </para>
 395   </refsect1>
 396
 397 </refentry>