man/sd_bus_error_add_map.xml

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