projects / systemd.git / blame
| Commit | Line | Data |
|---|---|---|
| 60f067b4 | 1 | '\" t |
| e3bff60a | 2 | .TH "SD_BUS_PATH_ENCODE" "3" "" "systemd 220" "sd_bus_path_encode" |
| 60f067b4 JS |
3 | .\" ----------------------------------------------------------------- |
| 4 | .\" * Define some portability stuff | |
| 5 | .\" ----------------------------------------------------------------- | |
| 6 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 7 | .\" http://bugs.debian.org/507673 | |
| 8 | .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html | |
| 9 | .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| 10 | .ie \n(.g .ds Aq \(aq | |
| 11 | .el .ds Aq ' | |
| 12 | .\" ----------------------------------------------------------------- | |
| 13 | .\" * set default formatting | |
| 14 | .\" ----------------------------------------------------------------- | |
| 15 | .\" disable hyphenation | |
| 16 | .nh | |
| 17 | .\" disable justification (adjust text to left margin only) | |
| 18 | .ad l | |
| 19 | .\" ----------------------------------------------------------------- | |
| 20 | .\" * MAIN CONTENT STARTS HERE * | |
| 21 | .\" ----------------------------------------------------------------- | |
| 22 | .SH "NAME" | |
| 23 | sd_bus_path_encode, sd_bus_path_decode \- Convert an external identifier into an object path and back | |
| 24 | .SH "SYNOPSIS" | |
| 25 | .sp | |
| 26 | .ft B | |
| 27 | .nf | |
| 28 | #include <systemd/sd\-bus\&.h> | |
| 29 | .fi | |
| 30 | .ft | |
| 31 | .HP \w'int\ sd_bus_path_encode('u | |
| 32 | .BI "int sd_bus_path_encode(const\ char\ *" "prefix" ", const\ char\ *" "external_id" ", char\ **" "ret_path" ");" | |
| 33 | .HP \w'int\ sd_bus_path_decode('u | |
| e735f4d4 | 34 | .BI "int sd_bus_path_decode(const\ char\ *" "path" ", const\ char\ *" "prefix" ", char\ **" "ret_external_id" ");" |
| 60f067b4 JS |
35 | .SH "DESCRIPTION" |
| 36 | .PP | |
| 37 | \fBsd_bus_path_encode()\fR | |
| 38 | and | |
| 39 | \fBsd_bus_path_decode()\fR | |
| 40 | 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\&. | |
| 41 | .PP | |
| 42 | \fBsd_bus_path_encode()\fR | |
| 43 | 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 | |
| 44 | "/", 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 | |
| 45 | \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 | |
| 46 | \fBsd_bus_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\&. | |
| 47 | .PP | |
| 48 | \fBsd_bus_path_decode()\fR | |
| 49 | reverses the operation of | |
| 50 | \fBsd_bus_path_encode()\fR | |
| 51 | 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 | |
| 52 | \fBNULL\fR\&. Otherwise, the string following the prefix is unescaped and returned in the external identifier string\&. | |
| 53 | .PP | |
| 54 | The escaping used will replace all characters which are invalid in a bus object path by | |
| 55 | "_", followed by a hexadecimal value\&. As a special case, the empty string will be replaced by a lone | |
| 56 | "_"\&. | |
| 57 | .SH "RETURN VALUE" | |
| 58 | .PP | |
| 59 | On success, | |
| 60 | \fBsd_bus_path_encode()\fR | |
| 61 | returns positive or 0, and a valid bus path in the return argument\&. On success, | |
| 62 | \fBsd_bus_path_decode()\fR | |
| 63 | 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 | |
| 64 | \fBfree\fR(3)\*(Aqd by the caller\&. | |
| 65 | .SH "NOTES" | |
| 66 | .PP | |
| 67 | \fBsd_bus_path_encode()\fR | |
| 68 | and | |
| 69 | \fBsd_bus_path_decode()\fR | |
| 70 | are available as a shared library, which can be compiled and linked to with the | |
| 71 | \fBlibsystemd\fR\ \&\fBpkg-config\fR(1) | |
| 72 | file\&. | |
| 73 | .SH "SEE ALSO" | |
| 74 | .PP | |
| 75 | \fBsystemd\fR(1), | |
| 76 | \fBsd-bus\fR(3), | |
| 77 | \fBfree\fR(3) |