SD_BUS_ERROR_ADD_MAP(3)

🌸 SD_BUS_ERROR_ADD_MAP(3) — the sd_bus_error_add_map page, bestie edition 🌸

okay so this is from the sd_bus_error_add_map manual (section 3, the library-calls girlies). it's all about teaching your D-Bus errors to speak errno. let's go 💅

---

✨ NAME ✨

sd_bus_error_add_map, sd_bus_error_map, SD_BUS_ERROR_MAP, SD_BUS_ERROR_END — extra sd-dbus error mappings, aka ✨the vibe translation layer✨

---

🦋 SYNOPSIS 🦋

#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_error_map *map);

---

💖 DESCRIPTION 💖

so sd_bus_error_add_map() is literally the function you call when you want to register more mappings that convert D-Bus errors into Linux errno-style errors. the mappings you define here get consulted by calls like sd_bus_error_set(3) or sd_bus_error_get_errno(3). by default there's already a whole pile of generic, standardized mappings that everyone knows about — those are documented in sd-bus-errors(3). this call is for adding further, application-specific ones. your own little custom lore, y'know? 🎀

the function takes a pointer to an array of sd_bus_error_map structures. a reference to that array gets added to the lookup tables for error mappings. and here's the important part, bestie — the structure is not copied. so it is absolutely essential that the array stays available and constant for the entire remaining runtime of the process. like, the whole rest of the program. no take-backs, no stack locals that vanish, none of that 🙈

the mapping array should be put together with a series of SD_BUS_ERROR_MAP() macro invocations, each taking 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. and fr fr, the array should not be put together without using these two macros. don't freestyle it 💀

also note the call is idempotent — it's totally safe to invoke it multiple times with the same parameter, and it'll only add the passed mapping array once. no duplicates, we love a queen who knows how to count 👑

and one more: the memory allocated by this call is not intended to be freed during the lifetime of the process. so do not free it explicitly. just let it live its life, main character energy ✨

---

🔥 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. known error codes are right below 👇

💀 Errors 💀

the returned errors may indicate the following problems:

• -EINVAL — the mapping array you specified is invalid. it's giving "girl what is this" 😭
• -ENOMEM — memory allocation failed. the computer simply said no 🤷‍♀️

---

🌈 NOTES 🌈

the functions described here are available as a shared library, which you can compile against and link to with the libsystemd pkg-config(1) file. slay 🫶

all functions listed here are thread-agnostic, and only a single thread may operate on a given object at any given time. different threads may access the same object at different times. multiple independent objects may be used from different threads in parallel. so like — share nicely, take turns, no chaos 💅

the code described here uses getenv(3), which is declared to be not multi-thread-safe. what does that mean for you? it means code calling the functions described here must not call setenv(3) from a parallel thread. the recommended move is to only do calls to setenv() from an early phase of the program, when no other threads have been started yet. early phase only, bestie 🧚

---

👑 HISTORY 👑

sd_bus_error_add_map() was added in version 221. a classic, an icon, a legend ⭐

---

🍓 SEE ALSO 🍓

systemd(1), sd-bus(3), sd_bus_error(3), sd-bus-errors(3), errno(3), strerror_r(3)

---

okay that's the whole page, no skips, no summaries, every flag and error intact 💖 and for the sign-off: this little beauty comes to you courtesy of systemd 261.3 — go forth and map those errors, you've got this 🦋✨