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