1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
|
'\" t
.TH "SD_BUS_PATH_ENCODE" "3" "" "systemd 241" "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 <systemd/sd\-bus\&.h>
.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
"NULL"
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, 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
\fBfree\fR(3)\*(Aqd by the caller\&.
.SH "NOTES"
.PP
These APIs are implemented as a shared library, which can be compiled and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
file\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsd-bus\fR(3),
\fBfree\fR(3)
|
