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