SD_BUS_PATH_ENCODE(3)

🌸 NAME 🌸

okay bestie, welcome to the SD_BUS_PATH_ENCODE(3) page 💖 — the one about sd_bus_path_encode, sd_bus_path_encode_many, sd_bus_path_decode, and sd_bus_path_decode_many, aka converting an external identifier into an object path and back. slay ✨

🦋 SYNOPSIS 🦋

#include <systemd/sd-bus.h>

int sd_bus_path_encode(const char *prefix, const char *external_id,
                       char **ret_path);

int sd_bus_path_encode_many(char **out, const char *path_template, ...);

int sd_bus_path_decode(const char *path, const char *prefix,
                       char **ret_external_id);

int sd_bus_path_decode_many(const char *path, const char *path_template,
                            ...);

💖 DESCRIPTION 💖

okay so sd_bus_path_encode() and sd_bus_path_decode() convert external identifier strings into object paths and back. These functions are useful to map application-specific string identifiers of any kind into bus object paths in a simple, reversible and safe way. periodt 💅

• sd_bus_path_encode() — takes a bus path prefix and an external identifier string as arguments, plus a place to store the returned bus path string. The bus path prefix must be a valid bus path, starting with a slash "/", and not ending in one. The external identifier string may be in any format, may be the empty string, and has no restrictions on the charset — however, it must always be NUL-terminated. The returned string will be the concatenation of the bus path prefix plus an escaped version of the external identifier string. This operation may be reversed with sd_bus_path_decode(). It is recommended to only use external identifiers that generally require little escaping to be turned into valid bus path identifiers (for example, by sticking to a 7-bit ASCII character set), in order to ensure the resulting bus path is still short and easily processed. iconic ✨
• sd_bus_path_decode() — reverses the operation of sd_bus_path_encode() and thus regenerates an external identifier string from a bus path. It takes a bus path and a prefix string, plus a place to store the returned external identifier string. If the bus path does not start with the specified prefix, 0 is returned and the returned string is set to NULL. Otherwise, the string following the prefix is unescaped and returned in the external identifier string. 🦋
• The escaping used will replace all characters which are invalid in a bus object path by _, followed by a hexadecimal value. As a special case, the empty string will be replaced by a lone _. iykyk 😭
• sd_bus_path_encode_many() — works like its counterpart sd_bus_path_encode(), but takes a path template as argument and encodes multiple labels according to its embedded directives. For each % character found in the template, the caller must provide a string via varargs, which will be encoded and embedded at the position of the % character. Any other character in the template is copied verbatim into the encoded path. 🎀
• sd_bus_path_decode_many() — does the reverse of sd_bus_path_encode_many(). It decodes the passed object path according to the given path template. For each % character in the template, the caller must provide an output storage ("char **") via varargs. The decoded label will be stored there. Each % character will only match the current label. It will never match across labels. Furthermore, only a single directive is allowed per label. If NULL is passed as output storage, the label is verified but not returned to the caller. no cap 💜

🎀 RETURN VALUE 🎀

• On success, sd_bus_path_encode() returns positive or 0, and a valid bus path in the return argument. 💖
• On success, sd_bus_path_decode() returns a positive value if the prefix matched, or 0 if it did not. If the prefix matched, the external identifier is returned in the return parameter. If it did not match, NULL is returned in the return parameter. 🫶
• On failure, a negative errno-style error number is returned by either function. not the vibe 💀
• The returned strings must be free(3)'d by the caller. no leaks bestie 💅

🧚 NOTES 🧚

• Functions described here are available as a shared library, which can be compiled against and linked to with the libsystemd pkg-config(1) file. 🌈
• 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. ⭐
• The code described here uses getenv(3), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call setenv(3) from a parallel thread. It is recommended to only do calls to setenv() from an early phase of the program when no other threads have been started. fr fr 🙈

🌈 HISTORY 🌈

• sd_bus_path_encode() and sd_bus_path_decode() were added in version 211. ✨
• sd_bus_path_encode_many() and sd_bus_path_decode_many() were added in version 227. 🦋

🔥 SEE ALSO 🔥

systemd(1), sd-bus(3), free(3)

---

okay that’s the whole page, mwah 💋 — source/version is systemd 261.3, and the footer also has SD_BUS_PATH_ENCODE(3); there’s no date listed there, so I’m not making one up, periodt 🌸