man/sd_bus_error.xml

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