sd_bus_error_add_map.xml revision 9d3e5d11bee9ab29a479e534622bb1b23daf9fab
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering This file is part of systemd.
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering Copyright 2015 Lennart Poettering
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering systemd is free software; you can redistribute it and/or modify it
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering under the terms of the GNU Lesser General Public License as published by
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering the Free Software Foundation; either version 2.1 of the License, or
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering (at your option) any later version.
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering systemd is distributed in the hope that it will be useful, but
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering Lesser General Public License for more details.
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering You should have received a copy of the GNU Lesser General Public License
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <refentryinfo>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering </authorgroup>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering </refentryinfo>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <refentrytitle>sd_bus_error_add_map</refentrytitle>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <refpurpose>Additional sd-dbus error mappings</refpurpose>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <refsynopsisdiv>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <funcsynopsis>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <funcsynopsisinfo>typedef struct {
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering const char *name;
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering} sd_bus_error_map;</funcsynopsisinfo>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering </funcsynopsis>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <constant>SD_BUS_ERROR_MAP(<replaceable>name</replaceable>, <replaceable>code</replaceable>)</constant>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <constant>SD_BUS_ERROR_MAP_END</constant>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <funcprototype>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <funcdef>int <function>sd_bus_error_add_map</function></funcdef>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <paramdef>const sd_bus_map *<parameter>map</parameter></paramdef>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering </funcprototype>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering </refsynopsisdiv>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <para>The <function>sd_bus_error_add_map()</function> call may be
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering used to register additional mappings for converting D-Bus errors
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering to Linux <varname>errno</varname>-style errors. The mappings
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering defined with this call are consulted by calls such as
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <citerefentry><refentrytitle>sd_bus_error_set</refentrytitle><manvolnum>3</manvolnum></citerefentry>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <citerefentry><refentrytitle>sd_bus_error_get_errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>. By
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering default a number of generic, standardized mappings are known, as
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Use
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering this call to add further, application-specific mappings.</para>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <para>The function takes a pointer to an array of
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <structname>sd_bus_error_map</structname> structures. A reference
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering to the specified array is added to the lookup tables for error
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering mappings. Note that the structure is not copied, it is hence
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering essential that the array stays available and constant during the
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering entire remaining runtime of the process.</para>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <para>The mapping array should be put together with a series of
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <constant>SD_BUS_ERROR_MAP()</constant> macro invocations, that
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering take a literal name string and a (positive)
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <varname>errno</varname>-style error number. The last entry of the
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering array should be an invocation of the
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <constant>SD_BUS_ERROR_MAP_END</constant> macro. The array should not be
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering put together without use of these two macros.</para>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <para>Note that the call is idempotent: it is safe to invoke it
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering multiple times with the parameter, which will only add the passed
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering mapping array once.</para>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <para>Note that the memory allocated by this call is not intended
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering to be freed during the lifetime of the process. It should not be
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering freed explicitly.</para>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <para><function>sd_bus_error_add_map()</function> returns a
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering positive value when the new array was added to the lookup
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering tables. It returns zero when the same array was already added
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering before. On error, a negative <varname>errno</varname>-style error
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering code is returned. See below for known error codes.</para>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <para>Returned errors may indicate the following problems:</para>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <variablelist>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <varlistentry>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <term><constant>-EINVAL</constant></term>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <listitem><para>The specified mapping array is invalid.</para></listitem>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering </varlistentry>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <varlistentry>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <term><constant>-ENOMEM</constant></term>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <listitem><para>Memory allocation failed.</para></listitem>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering </varlistentry>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering </variablelist>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <para>The various error definitions described here are available
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering as a shared library, which can be compiled and linked to with the
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <constant>libsystemd</constant> <citerefentry
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <citerefentry><refentrytitle>sd_bus_error</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <citerefentry project='man-pages'><refentrytitle>errno</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
9d3e5d11bee9ab29a479e534622bb1b23daf9fabLennart Poettering <citerefentry project='die-net'><refentrytitle>strerror_r</refentrytitle><manvolnum>3</manvolnum></citerefentry>