sd_bus_path_encode - Man Page

#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, ​...);

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​.

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​.

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 "_"​.

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​.

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 prefixed 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​. The returned strings must be free(3)'d by the caller​.

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​.

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​.

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