--- name: "sd_bus_path_decode" section: "3" platform: "linux" package: "libsystemd-dev" version: "257.13-1~deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/sd_bus_path_encode" --- # sd\_bus\_path\_decode(3) Convert an external identifier into an object path and back Part of [sd\_bus\_path\_encode(3)](/sd_bus_path_encode/3.md). ## NAME sd\_bus\_path\_encode, sd\_bus\_path\_encode\_many, sd\_bus\_path\_decode, sd\_bus\_path\_decode\_many - Convert an external identifier into an object path and back ## SYNOPSIS ``` #include ``` **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 **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. ## 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 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)](/free/3.md)'d by the caller. ## NOTES Functions described here are available as a shared library, which can be compiled against and linked to with the **libsystemd** [**pkg-config**(1)](/pkg-config/1.md) file. The code described here uses [**getenv**(3)](/getenv/3.md), which is declared to be not multi-thread-safe. This means that the code calling the functions described here must not call [**setenv**(3)](/setenv/3.md) 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. ## 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)](/systemd/1.md), [**sd-bus**(3)](/sd-bus/3.md), [**free**(3)](/free/3.md)