diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man3/sd_bus_path_encode.3')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man3/sd_bus_path_encode.3 | 105 |
1 files changed, 0 insertions, 105 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/sd_bus_path_encode.3 b/upstream/opensuse-tumbleweed/man3/sd_bus_path_encode.3 deleted file mode 100644 index 11076cab..00000000 --- a/upstream/opensuse-tumbleweed/man3/sd_bus_path_encode.3 +++ /dev/null @@ -1,105 +0,0 @@ -'\" t -.TH "SD_BUS_PATH_ENCODE" "3" "" "systemd 254" "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 -\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 "SEE ALSO" -.PP -\fBsystemd\fR(1), -\fBsd-bus\fR(3), -\fBfree\fR(3) |