mirror of
https://git.proxmox.com/git/systemd
synced 2025-05-29 18:06:10 +00:00
78 lines
4.0 KiB
Groff
78 lines
4.0 KiB
Groff
'\" t
|
|
.TH "SD_BUS_PATH_ENCODE" "3" "" "systemd 219" "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_decode \- 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_decode('u
|
|
.BI "int sd_bus_path_decode(const\ char\ *" "path" ", const\ char\ *" "prefix" ", char\ **" "ret_external_id" ");"
|
|
.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_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
|
|
"_"\&.
|
|
.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
|
|
\fBsd_bus_path_encode()\fR
|
|
and
|
|
\fBsd_bus_path_decode()\fR
|
|
are available 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)
|