Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_path_encode.3

raw
1 '\" t
2 .TH "SD_BUS_PATH_ENCODE" "3" "" "systemd 261~rc3" "sd_bus_path_encode"
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_encode_many, sd_bus_path_decode, sd_bus_path_decode_many \- 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_encode_many('u
34 .BI "int sd_bus_path_encode_many(char\ **" "out" ", const\ char\ *" "path_template" ", \&...);"
35 .HP \w'int\ sd_bus_path_decode('u
36 .BI "int sd_bus_path_decode(const\ char\ *" "path" ", const\ char\ *" "prefix" ", char\ **" "ret_external_id" ");"
37 .HP \w'int\ sd_bus_path_decode_many('u
38 .BI "int sd_bus_path_decode_many(const\ char\ *" "path" ", const\ char\ *" "path_template" ", \&...);"
39 .SH "DESCRIPTION"
40 .PP
41 \fBsd_bus_path_encode()\fR
42 and
43 \fBsd_bus_path_decode()\fR
44 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\&.
45 .PP
46 \fBsd_bus_path_encode()\fR
47 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
48 "/", 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
49 \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
50 \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\&.
51 .PP
52 \fBsd_bus_path_decode()\fR
53 reverses the operation of
54 \fBsd_bus_path_encode()\fR
55 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
56 \fBNULL\fR\&. Otherwise, the string following the prefix is unescaped and returned in the external identifier string\&.
57 .PP
58 The escaping used will replace all characters which are invalid in a bus object path by
59 "_", followed by a hexadecimal value\&. As a special case, the empty string will be replaced by a lone
60 "_"\&.
61 .PP
62 \fBsd_bus_path_encode_many()\fR
63 works like its counterpart
64 \fBsd_bus_path_encode()\fR, but takes a path template as argument and encodes multiple labels according to its embedded directives\&. For each
65 "%"
66 character found in the template, the caller must provide a string via varargs, which will be encoded and embedded at the position of the
67 "%"
68 character\&. Any other character in the template is copied verbatim into the encoded path\&.
69 .PP
70 \fBsd_bus_path_decode_many()\fR
71 does the reverse of
72 \fBsd_bus_path_encode_many()\fR\&. It decodes the passed object path according to the given path template\&. For each
73 "%"
74 character in the template, the caller must provide an output storage ("char **") via varargs\&. The decoded label will be stored there\&. Each
75 "%"
76 character will only match the current label\&. It will never match across labels\&. Furthermore, only a single directive is allowed per label\&. If
77 \fBNULL\fR
78 is passed as output storage, the label is verified but not returned to the caller\&.
79 .SH "RETURN VALUE"
80 .PP
81 On success,
82 \fBsd_bus_path_encode()\fR
83 returns positive or 0, and a valid bus path in the return argument\&. On success,
84 \fBsd_bus_path_decode()\fR
85 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,
86 \fBNULL\fR
87 is returned in the return parameter\&. On failure, a negative errno\-style error number is returned by either function\&. The returned strings must be
88 \fBfree\fR(3)\*(Aqd by the caller\&.
89 .SH "NOTES"
90 .PP
91 Functions described here are available as a shared library, which can be compiled against and linked to with the
92 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
93 file\&.
94 .PP
95 The code described here uses
96 \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
97 \fBsetenv\fR(3)
98 from a parallel thread\&. It is recommended to only do calls to
99 \fBsetenv()\fR
100 from an early phase of the program when no other threads have been started\&.
101 .SH "HISTORY"
102 .PP
103 \fBsd_bus_path_encode()\fR
104 and
105 \fBsd_bus_path_decode()\fR
106 were added in version 211\&.
107 .PP
108 \fBsd_bus_path_encode_many()\fR
109 and
110 \fBsd_bus_path_decode_many()\fR
111 were added in version 227\&.
112 .SH "SEE ALSO"
113 .PP
114 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBfree\fR(3)