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