'\" t .TH "SD_BUS_PATH_ENCODE" "3" "" "systemd 256.8" "sd_bus_path_encode" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "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 .SH "SYNOPSIS" .sp .ft B .nf #include .fi .ft .HP \w'int\ sd_bus_path_encode('u .BI "int sd_bus_path_encode(const\ char\ *" "prefix" ", const\ char\ *" "external_id" ", char\ **" "ret_path" ");" .HP \w'int\ sd_bus_path_encode_many('u .BI "int sd_bus_path_encode_many(char\ **" "out" ", const\ char\ *" "path_template" ", \&...);" .HP \w'int\ sd_bus_path_decode('u .BI "int sd_bus_path_decode(const\ char\ *" "path" ", const\ char\ *" "prefix" ", char\ **" "ret_external_id" ");" .HP \w'int\ sd_bus_path_decode_many('u .BI "int sd_bus_path_decode_many(const\ char\ *" "path" ", const\ char\ *" "path_template" ", \&...);" .SH "DESCRIPTION" .PP \fBsd_bus_path_encode()\fR and \fBsd_bus_path_decode()\fR 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\&. .PP \fBsd_bus_path_encode()\fR 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\ \&\(em however, it must always be \fBNUL\fR\-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 \fBsd_bus_path_decode()\fR\&. 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\&. .PP \fBsd_bus_path_decode()\fR reverses the operation of \fBsd_bus_path_encode()\fR 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 \fBNULL\fR\&. Otherwise, the string following the prefix is unescaped and returned in the external identifier string\&. .PP 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 "_"\&. .PP \fBsd_bus_path_encode_many()\fR works like its counterpart \fBsd_bus_path_encode()\fR, 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\&. .PP \fBsd_bus_path_decode_many()\fR does the reverse of \fBsd_bus_path_encode_many()\fR\&. 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 \fBNULL\fR is passed as output storage, the label is verified but not returned to the caller\&. .SH "RETURN VALUE" .PP On success, \fBsd_bus_path_encode()\fR returns positive or 0, and a valid bus path in the return argument\&. On success, \fBsd_bus_path_decode()\fR 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, \fBNULL\fR is returned in the return parameter\&. On failure, a negative errno\-style error number is returned by either function\&. The returned strings must be \fBfree\fR(3)\*(Aqd by the caller\&. .SH "NOTES" .PP Functions described here are available as a shared library, which can be compiled against and linked to with the \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) file\&. .PP The code described here uses \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call \fBsetenv\fR(3) from a parallel thread\&. It is recommended to only do calls to \fBsetenv()\fR from an early phase of the program when no other threads have been started\&. .SH "HISTORY" .PP \fBsd_bus_path_encode()\fR and \fBsd_bus_path_decode()\fR were added in version 211\&. .PP \fBsd_bus_path_encode_many()\fR and \fBsd_bus_path_decode_many()\fR were added in version 227\&. .SH "SEE ALSO" .PP \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBfree\fR(3)