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