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