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