2018-07-03 00:15:39 +03:00
<?xml version='1.0'?>
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2014-03-11 22:03:50 +04:00
2018-08-03 18:34:40 +03:00
<refentry id= "sd_bus_path_encode" xmlns:xi= "http://www.w3.org/2001/XInclude" >
2014-03-11 22:03:50 +04:00
<refentryinfo >
<title > sd_bus_path_encode</title>
<productname > systemd</productname>
</refentryinfo>
<refmeta >
<refentrytitle > sd_bus_path_encode</refentrytitle>
<manvolnum > 3</manvolnum>
</refmeta>
<refnamediv >
<refname > sd_bus_path_encode</refname>
2015-09-25 20:05:23 +03:00
<refname > sd_bus_path_encode_many</refname>
2014-03-11 22:03:50 +04:00
<refname > sd_bus_path_decode</refname>
2015-09-25 20:05:23 +03:00
<refname > sd_bus_path_decode_many</refname>
2014-03-11 22:03:50 +04:00
<refpurpose > Convert an external identifier into an object path and back</refpurpose>
</refnamediv>
<refsynopsisdiv >
<funcsynopsis >
<funcsynopsisinfo > #include < systemd/sd-bus.h> </funcsynopsisinfo>
<funcprototype >
<funcdef > int <function > sd_bus_path_encode</function> </funcdef>
<paramdef > const char *<parameter > prefix</parameter> </paramdef>
<paramdef > const char *<parameter > external_id</parameter> </paramdef>
<paramdef > char **<parameter > ret_path</parameter> </paramdef>
</funcprototype>
2015-09-25 20:05:23 +03:00
<funcprototype >
<funcdef > int <function > sd_bus_path_encode_many</function> </funcdef>
<paramdef > char **<parameter > out</parameter> </paramdef>
<paramdef > const char *<parameter > path_template</parameter> </paramdef>
2016-12-12 01:01:07 +03:00
<paramdef > …</paramdef>
2015-09-25 20:05:23 +03:00
</funcprototype>
2014-03-11 22:03:50 +04:00
<funcprototype >
<funcdef > int <function > sd_bus_path_decode</function> </funcdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
2015-02-10 19:28:34 +03:00
<paramdef > const char *<parameter > prefix</parameter> </paramdef>
2014-03-11 22:03:50 +04:00
<paramdef > char **<parameter > ret_external_id</parameter> </paramdef>
</funcprototype>
2015-09-25 20:05:23 +03:00
<funcprototype >
<funcdef > int <function > sd_bus_path_decode_many</function> </funcdef>
<paramdef > const char *<parameter > path</parameter> </paramdef>
<paramdef > const char *<parameter > path_template</parameter> </paramdef>
2016-12-12 01:01:07 +03:00
<paramdef > …</paramdef>
2015-09-25 20:05:23 +03:00
</funcprototype>
2014-03-11 22:03:50 +04:00
</funcsynopsis>
</refsynopsisdiv>
<refsect1 >
<title > Description</title>
<para > <function > sd_bus_path_encode()</function> and
<function > sd_bus_path_decode()</function> 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.</para>
<para > <function > sd_bus_path_encode()</function> 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
2014-05-08 03:28:45 +04:00
<literal > /</literal> , 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 — however, it must
2014-03-11 22:03:50 +04:00
always be <constant > NUL</constant> -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
2018-07-26 21:00:36 +03:00
reversed with <function > sd_bus_path_decode()</function> . It is
2014-05-08 03:28:45 +04:00
recommended to only use external identifiers that generally
2014-03-11 22:03:50 +04:00
require little escaping to be turned into valid bus path
2014-05-08 03:28:45 +04:00
identifiers (for example, by sticking to a 7-bit ASCII character
2014-03-11 22:03:50 +04:00
set), in order to ensure the resulting bus path is still short and
easily processed.</para>
<para > <function > sd_bus_path_decode()</function> reverses the
operation of <function > sd_bus_path_encode()</function> 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
2014-05-08 03:28:45 +04:00
string is set to <constant > NULL</constant> . Otherwise, the
2014-03-11 22:03:50 +04:00
string following the prefix is unescaped and returned in the
external identifier string.</para>
2014-05-08 03:28:44 +04:00
<para > The escaping used will replace all characters which are
2014-05-08 03:28:45 +04:00
invalid in a bus object path by <literal > _</literal> , followed by a
2014-03-11 22:03:50 +04:00
hexadecimal value. As a special case, the empty string will be
replaced by a lone <literal > _</literal> .</para>
2015-09-25 20:05:23 +03:00
<para > <function > sd_bus_path_encode_many()</function> works like
its counterpart <function > sd_bus_path_encode()</function> , but
2014-08-03 09:11:12 +04:00
takes a path template as argument and encodes multiple labels
2015-09-25 20:05:23 +03:00
according to its embedded directives. For each
<literal > %</literal> character found in the template, the caller
2014-08-03 09:11:12 +04:00
must provide a string via varargs, which will be encoded and
2015-09-25 20:05:23 +03:00
embedded at the position of the <literal > %</literal> character.
Any other character in the template is copied verbatim into the
encoded path.</para>
<para > <function > sd_bus_path_decode_many()</function> does the
reverse of <function > sd_bus_path_encode_many()</function> . It
2014-08-03 09:11:12 +04:00
decodes the passed object path according to the given
path template. For each <literal > %</literal> character in the
2015-09-25 20:05:23 +03:00
template, the caller must provide an output storage
2014-08-03 09:11:12 +04:00
(<literal > char **</literal> ) via varargs. The decoded label
2015-09-25 20:05:23 +03:00
will be stored there. Each <literal > %</literal> character will
only match the current label. It will never match across labels.
2014-08-03 09:11:37 +04:00
Furthermore, only a single directive is allowed per label.
2020-11-12 10:58:00 +03:00
If <constant > NULL</constant> is passed as output storage, the
2015-09-25 20:05:23 +03:00
label is verified but not returned to the caller.</para>
2014-03-11 22:03:50 +04:00
</refsect1>
<refsect1 >
<title > Return Value</title>
<para > On success, <function > sd_bus_path_encode()</function>
returns positive or 0, and a valid bus path in the return
argument. On success, <function > sd_bus_path_decode()</function>
returns a positive value if the prefixed matched, or 0 if it
2014-05-08 03:28:45 +04:00
did not. If the prefix matched, the external identifier is returned
2020-11-12 10:58:00 +03:00
in the return parameter. If it did not match, <constant > NULL</constant> is returned in
2014-03-11 22:03:50 +04:00
the return parameter. On failure, a negative errno-style error
number is returned by either function. The returned strings must
be
man: add a mapping for external manpages
It is annoying when we have dead links on fd.o.
Add project='man-pages|die-net|archlinux' to <citerefentry>-ies.
In generated html, add external links to
http://man7.org/linux/man-pages/man, http://linux.die.net/man/,
https://www.archlinux.org/.
By default, pages in sections 2 and 4 go to man7, since Michael
Kerrisk is the autorative source on kernel related stuff.
The rest of links goes to linux.die.net, because they have the
manpages.
Except for the pacman stuff, since it seems to be only available from
archlinux.org.
Poor gummiboot gets no link, because gummitboot(8) ain't to be found
on the net. According to common wisdom, that would mean that it does
not exist. But I have seen Kay using it, so I know it does, and
deserves to be found. Can somebody be nice and put it up somewhere?
2014-07-08 02:25:54 +04:00
<citerefentry project= 'man-pages' > <refentrytitle > free</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> 'd
2014-03-11 22:03:50 +04:00
by the caller.</para>
</refsect1>
2018-08-03 18:34:40 +03:00
<xi:include href= "libsystemd-pkgconfig.xml" />
2014-03-11 22:03:50 +04:00
2023-09-04 15:46:35 +03:00
<refsect1 >
<title > History</title>
2023-09-18 19:44:26 +03:00
<para > <function > sd_bus_path_encode()</function> and
<function > sd_bus_path_decode()</function> were added in version 211.</para>
<para > <function > sd_bus_path_encode_many()</function> and
<function > sd_bus_path_decode_many()</function> were added in version 227.</para>
2023-09-04 15:46:35 +03:00
</refsect1>
2014-03-11 22:03:50 +04:00
<refsect1 >
<title > See Also</title>
2023-12-22 21:09:32 +03:00
<para > <simplelist type= "inline" >
<member > <citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > sd-bus</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
<member > <citerefentry project= 'man-pages' > <refentrytitle > free</refentrytitle> <manvolnum > 3</manvolnum> </citerefentry> </member>
</simplelist> </para>
2014-03-11 22:03:50 +04:00
</refsect1>
</refentry>