# sd_bus_path_encode

## 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 <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



           **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)'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) file.
    
           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.
    


* * *