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