man/sd_bus_error_add_map.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
   9 <refentry id="sd_bus_error_add_map">
  10
  11   <refentryinfo>
  12     <title>sd_bus_error_add_map</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>sd_bus_error_add_map</refentrytitle>
  18     <manvolnum>3</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>sd_bus_error_add_map</refname>
  23     <refname>sd_bus_error_map</refname>
  24     <refname>SD_BUS_ERROR_MAP</refname>
  25     <refname>SD_BUS_ERROR_END</refname>
  26
  27     <refpurpose>Additional sd-dbus error mappings</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <funcsynopsis>
  32       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  33
  34       <funcsynopsisinfo>typedef struct {
  35         const char *name;
  36         int code;
  37         …
  38 } sd_bus_error_map;</funcsynopsisinfo>
  39
  40     </funcsynopsis>
  41
  42       <para>
  43         <constant>SD_BUS_ERROR_MAP(<replaceable>name</replaceable>, <replaceable>code</replaceable>)</constant>
  44       </para>
  45       <para>
  46         <constant>SD_BUS_ERROR_MAP_END</constant>
  47       </para>
  48
  49       <funcprototype>
  50         <funcdef>int <function>sd_bus_error_add_map</function></funcdef>
  51         <paramdef>const sd_bus_map *<parameter>map</parameter></paramdef>
  52       </funcprototype>
  53
  54   </refsynopsisdiv>
  55
  56   <refsect1>
  57     <title>Description</title>
  58
  59     <para>The <function>sd_bus_error_add_map()</function> call may be
  60     used to register additional mappings for converting D-Bus errors
  61     to Linux <varname>errno</varname>-style errors. The mappings
  62     defined with this call are consulted by calls such as
  63     <citerefentry><refentrytitle>sd_bus_error_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  64     or
  65     <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. By
  66     default, a number of generic, standardized mappings are known, as
  67     documented in
  68     <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Use
  69     this call to add further, application-specific mappings.</para>
  70
  71     <para>The function takes a pointer to an array of
  72     <structname>sd_bus_error_map</structname> structures. A reference
  73     to the specified array is added to the lookup tables for error
  74     mappings. Note that the structure is not copied, and that it is hence
  75     essential that the array stays available and constant during the
  76     entire remaining runtime of the process.</para>
  77
  78     <para>The mapping array should be put together with a series of
  79     <constant>SD_BUS_ERROR_MAP()</constant> macro invocations that
  80     take a literal name string and a (positive)
  81     <varname>errno</varname>-style error number. The last entry of the
  82     array should be an invocation of the
  83     <constant>SD_BUS_ERROR_MAP_END</constant> macro. The array should not be
  84     put together without use of these two macros.</para>
  85
  86     <para>Note that the call is idempotent: it is safe to invoke it
  87     multiple times with the parameter, which will only add the passed
  88     mapping array once.</para>
  89
  90     <para>Note that the memory allocated by this call is not intended
  91     to be freed during the lifetime of the process. It should not be
  92     freed explicitly.</para>
  93   </refsect1>
  94
  95   <refsect1>
  96     <title>Return Value</title>
  97
  98     <para><function>sd_bus_error_add_map()</function> returns a
  99     positive value when the new array was added to the lookup
 100     tables. It returns zero when the same array was already added
 101     before. On error, a negative <varname>errno</varname>-style error
 102     code is returned. See below for known error codes.</para>
 103   </refsect1>
 104
 105   <refsect1>
 106     <title>Errors</title>
 107
 108     <para>Returned errors may indicate the following problems:</para>
 109
 110     <variablelist>
 111
 112       <varlistentry>
 113         <term><constant>-EINVAL</constant></term>
 114
 115         <listitem><para>The specified mapping array is invalid.</para></listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><constant>-ENOMEM</constant></term>
 120
 121         <listitem><para>Memory allocation failed.</para></listitem>
 122       </varlistentry>
 123     </variablelist>
 124   </refsect1>
 125
 126   <refsect1>
 127     <title>Notes</title>
 128
 129     <para>The various error definitions described here are available
 130     as a shared library, which can be compiled and linked to with the
 131     <constant>libelogind</constant> <citerefentry
 132     project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 133     file.</para>
 134   </refsect1>
 135
 136   <refsect1>
 137     <title>See Also</title>
 138
 139     <para>
 140       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 141       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 142       <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 143       <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 144       <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 145       <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 146     </para>
 147   </refsect1>
 148
 149 </refentry>