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