From 9d3e5d11bee9ab29a479e534622bb1b23daf9fab Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 23 Jun 2015 19:37:28 +0200 Subject: man: fully document sd-bus' error APIs [@zonque: Some minor nits fixed as pointed out by @ronnychevalier, dropped class='sd-bus-errors' to fix python logic] --- man/sd_bus_error_add_map.xml | 173 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 man/sd_bus_error_add_map.xml (limited to 'man/sd_bus_error_add_map.xml') diff --git a/man/sd_bus_error_add_map.xml b/man/sd_bus_error_add_map.xml new file mode 100644 index 0000000000..3fca63be4a --- /dev/null +++ b/man/sd_bus_error_add_map.xml @@ -0,0 +1,173 @@ + + + + + + + + + sd_bus_error_add_map + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + sd_bus_error_add_map + 3 + + + + sd_bus_error_add_map + sd_bus_error_map + SD_BUS_ERROR_MAP + SD_BUS_ERROR_END + + Additional sd-dbus error mappings + + + + + #include <systemd/sd-bus.h> + + typedef struct { + const char *name; + int code; + ... +} sd_bus_error_map; + + + + + SD_BUS_ERROR_MAP(name, code) + + + SD_BUS_ERROR_MAP_END + + + + int sd_bus_error_add_map + const sd_bus_map *map + + + + + + Description + + The sd_bus_error_add_map() call may be + used to register additional mappings for converting D-Bus errors + to Linux errno-style errors. The mappings + defined with this call are consulted by calls such as + sd_bus_error_set3 + or + sd_bus_error_get_errno3. By + default a number of generic, standardized mappings are known, as + documented in + sd-bus-errors3. Use + this call to add further, application-specific mappings. + + The function takes a pointer to an array of + sd_bus_error_map structures. A reference + to the specified array is added to the lookup tables for error + mappings. Note that the structure is not copied, it is hence + essential that the array stays available and constant during the + entire remaining runtime of the process. + + The mapping array should be put together with a series of + SD_BUS_ERROR_MAP() macro invocations, that + take a literal name string and a (positive) + errno-style error number. The last entry of the + array should be an invocation of the + SD_BUS_ERROR_MAP_END macro. The array should not be + put together without use of these two macros. + + Note that the call is idempotent: it is safe to invoke it + multiple times with the parameter, which will only add the passed + mapping array once. + + Note that the memory allocated by this call is not intended + to be freed during the lifetime of the process. It should not be + freed explicitly. + + + + Return Value + + sd_bus_error_add_map() returns a + positive value when the new array was added to the lookup + tables. It returns zero when the same array was already added + before. On error, a negative errno-style error + code is returned. See below for known error codes. + + + + Errors + + Returned errors may indicate the following problems: + + + + + -EINVAL + + The specified mapping array is invalid. + + + + -ENOMEM + + Memory allocation failed. + + + + + + Notes + + The various error definitions described here are available + as a shared library, which can be compiled and linked to with the + libsystemd pkg-config1 + file. + + + + See Also + + + systemd1, + sd-bus3, + sd_bus_error3, + sd-bus-errors3, + errno3, + strerror_r3 + + + + -- cgit v1.2.3-54-g00ecf