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