3802a3d3d7af51ddff31943d5514382f01265770Lennart Poettering<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek This file is part of systemd.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Copyright 2014 Zbigniew Jędrzejewski-Szmek
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is free software; you can redistribute it and/or modify it
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek under the terms of the GNU Lesser General Public License as published by
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek the Free Software Foundation; either version 2.1 of the License, or
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek (at your option) any later version.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek systemd is distributed in the hope that it will be useful, but
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek WITHOUT ANY WARRANTY; without even the implied warranty of
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek Lesser General Public License for more details.
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek You should have received a copy of the GNU Lesser General Public License
b975b0d514321f169b3c4599a8ea92e13741b4e4Zbigniew Jędrzejewski-Szmek along with systemd; If not, see <http://www.gnu.org/licenses/>.
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <refentryinfo>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <contrib>A monkey with a typewriter</contrib>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </authorgroup>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </refentryinfo>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <refentrytitle>sd_bus_path_encode</refentrytitle>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <refpurpose>Convert an external identifier into an object path and back</refpurpose>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <refsynopsisdiv>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcsynopsis>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcprototype>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcdef>int <function>sd_bus_path_encode</function></funcdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>const char *<parameter>prefix</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>const char *<parameter>external_id</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>char **<parameter>ret_path</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </funcprototype>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <funcprototype>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <funcdef>int <function>sd_bus_path_encode_many</function></funcdef>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <paramdef>char **<parameter>out</parameter></paramdef>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <paramdef>const char *<parameter>path_template</parameter></paramdef>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann </funcprototype>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcprototype>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <funcdef>int <function>sd_bus_path_decode</function></funcdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>const char *<parameter>path</parameter></paramdef>
53d6837510478e1275b294654663635466cbafc7Tom Gundersen <paramdef>const char *<parameter>prefix</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <paramdef>char **<parameter>ret_external_id</parameter></paramdef>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </funcprototype>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <funcprototype>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <funcdef>int <function>sd_bus_path_decode_many</function></funcdef>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <paramdef>const char *<parameter>path</parameter></paramdef>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <paramdef>const char *<parameter>path_template</parameter></paramdef>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann </funcprototype>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </funcsynopsis>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering </refsynopsisdiv>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para><function>sd_bus_path_encode()</function> and
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <function>sd_bus_path_decode()</function> convert external
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering identifier strings into object paths and back. These functions are
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering useful to map application-specific string identifiers of any kind
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering into bus object paths in a simple, reversible and safe way.</para>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para><function>sd_bus_path_encode()</function> takes a bus path
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering prefix and an external identifier string as arguments, plus a
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering place to store the returned bus path string. The bus path prefix
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering must be a valid bus path, starting with a slash
b8bde11658366290521e3d03316378b482600323Jan Engelhardt <literal>/</literal>, and not ending in one. The external
b8bde11658366290521e3d03316378b482600323Jan Engelhardt identifier string may be in any format, may be the empty string,
b8bde11658366290521e3d03316378b482600323Jan Engelhardt and has no restrictions on the charset — however, it must
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering always be <constant>NUL</constant>-terminated. The returned string
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering will be the concatenation of the bus path prefix plus an escaped
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering version of the external identifier string. This operation may be
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering reversed with <function>sd_bus_decode()</function>. It is
b8bde11658366290521e3d03316378b482600323Jan Engelhardt recommended to only use external identifiers that generally
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering require little escaping to be turned into valid bus path
b8bde11658366290521e3d03316378b482600323Jan Engelhardt identifiers (for example, by sticking to a 7-bit ASCII character
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering set), in order to ensure the resulting bus path is still short and
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering easily processed.</para>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para><function>sd_bus_path_decode()</function> reverses the
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering operation of <function>sd_bus_path_encode()</function> and thus
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering regenerates an external identifier string from a bus path. It
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering takes a bus path and a prefix string, plus a place to store the
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering returned external identifier string. If the bus path does not
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering start with the specified prefix, 0 is returned and the returned
b8bde11658366290521e3d03316378b482600323Jan Engelhardt string is set to <constant>NULL</constant>. Otherwise, the
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering string following the prefix is unescaped and returned in the
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering external identifier string.</para>
dca348bcbb462305864526c587495a14a76bfcdeJan Engelhardt <para>The escaping used will replace all characters which are
b8bde11658366290521e3d03316378b482600323Jan Engelhardt invalid in a bus object path by <literal>_</literal>, followed by a
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering hexadecimal value. As a special case, the empty string will be
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering replaced by a lone <literal>_</literal>.</para>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <para><function>sd_bus_path_encode_many()</function> works like
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann its counterpart <function>sd_bus_path_encode()</function>, but
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt takes a path template as argument and encodes multiple labels
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann according to its embedded directives. For each
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <literal>%</literal> character found in the template, the caller
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt must provide a string via varargs, which will be encoded and
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann embedded at the position of the <literal>%</literal> character.
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann Any other character in the template is copied verbatim into the
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann encoded path.</para>
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann <para><function>sd_bus_path_decode_many()</function> does the
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann reverse of <function>sd_bus_path_encode_many()</function>. It
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt decodes the passed object path according to the given
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt path template. For each <literal>%</literal> character in the
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann template, the caller must provide an output storage
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt (<literal>char **</literal>) via varargs. The decoded label
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann will be stored there. Each <literal>%</literal> character will
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann only match the current label. It will never match across labels.
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt Furthermore, only a single directive is allowed per label.
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann If <literal>NULL</literal> is passed as output storage, the
dfb815c36df6e5f2089672b1d986d38b44c7ad17David Herrmann label is verified but not returned to the caller.</para>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para>On success, <function>sd_bus_path_encode()</function>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering returns positive or 0, and a valid bus path in the return
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering argument. On success, <function>sd_bus_path_decode()</function>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering returns a positive value if the prefixed matched, or 0 if it
b8bde11658366290521e3d03316378b482600323Jan Engelhardt did not. If the prefix matched, the external identifier is returned
b8bde11658366290521e3d03316378b482600323Jan Engelhardt in the return parameter. If it did not match, NULL is returned in
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering the return parameter. On failure, a negative errno-style error
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering number is returned by either function. The returned strings must
5aded369782f28255bc6b494ca905d7acaea7a56Zbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>'d
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering by the caller.</para>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <para><function>sd_bus_path_encode()</function> and
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <function>sd_bus_path_decode()</function> are available as a
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering shared library, which can be compiled and linked to with the
5aded369782f28255bc6b494ca905d7acaea7a56Zbigniew Jędrzejewski-Szmek <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
a6278b88305b237b02eabff0d870b57fe851822dLennart Poettering <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
5aded369782f28255bc6b494ca905d7acaea7a56Zbigniew Jędrzejewski-Szmek <citerefentry project='man-pages'><refentrytitle>free</refentrytitle><manvolnum>3</manvolnum></citerefentry>