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