shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-01 17:51:22 +03:00
Code
b3f259d056
systemd/man/sd_bus_path_encode.xml

157 lines
6.7 KiB
XML
Raw Normal View History

man: drop mode line in file headers This is already included in .dir-locals, so we don't need it in the files themselves.
2018-07-03 00:15:39 +03:00
<?xml version='1.0'?>
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
man: revert dynamic paths for split-usr setups This did not really work out as we had hoped. Trying to do this upstream introduced several problems that probably makes it better suited as a downstream patch after all. At any rate, it is not releaseable in the current state, so we at least need to revert this before the release. * by adjusting the path to binaries, but not do the same thing to the search path we end up with inconsistent man-pages. Adjusting the search path too would be quite messy, and it is not at all obvious that this is worth the effort, but at any rate it would have to be done before we could ship this. * this means that distributed man-pages does not make sense as they depend on config options, and for better or worse we are still distributing man pages, so that is something that definitely needs sorting out before we could ship with this patch. * we have long held that split-usr is only minimally supported in order to boot, and something we hope will eventually go away. So before we start adding even more magic/effort in order to make this work nicely, we should probably question if it makes sense at all.
2015-06-18 20:47:44 +03:00
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
<!--
Add SPDX license identifiers to man pages
2017-11-18 19:22:32 +03:00
SPDX-License-Identifier: LGPL-2.1+
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
-->
man: include libsystemd-pkgconfig.xml in a few more man pages for some reason this was forgotten for a couple of sd_bus man pages, let's fix that.
2018-08-03 18:34:40 +03:00
<refentry id="sd_bus_path_encode" xmlns:xi="http://www.w3.org/2001/XInclude">
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
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>
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
2015-09-25 20:05:23 +03:00
<refname>sd_bus_path_encode_many</refname>
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
<refname>sd_bus_path_decode</refname>
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
2015-09-25 20:05:23 +03:00
<refname>sd_bus_path_decode_many</refname>
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
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 &lt;systemd/sd-bus.h&gt;</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>
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
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>
man: use unicode ellipsis in more places As requested in https://github.com/systemd/systemd/pull/4864#pullrequestreview-12372557. docbook will substitute triple dots for the ellipsis in man output, so this has no effect on the troff output, only on HTML, making it infinitesimally nicer. In some places we show output from programs, which use dots, and those places should not be changed. In some tables, the alignment would change if dots were changed to the ellipsis which is only one character. Since docbook replaces the ellipsis automatically, we should leave those be. This patch changes all other places.
2016-12-12 01:01:07 +03:00
<paramdef>…</paramdef>
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
2015-09-25 20:05:23 +03:00
</funcprototype>
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
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>
man: sd_bus_path_encode - fix order of arguments
2015-02-10 19:28:34 +03:00
<paramdef>const char *<parameter>prefix</parameter></paramdef>
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
<paramdef>char **<parameter>ret_external_id</parameter></paramdef>
</funcprototype>
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
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>
man: use unicode ellipsis in more places As requested in https://github.com/systemd/systemd/pull/4864#pullrequestreview-12372557. docbook will substitute triple dots for the ellipsis in man output, so this has no effect on the troff output, only on HTML, making it infinitesimally nicer. In some places we show output from programs, which use dots, and those places should not be changed. In some tables, the alignment would change if dots were changed to the ellipsis which is only one character. Since docbook replaces the ellipsis automatically, we should leave those be. This patch changes all other places.
2016-12-12 01:01:07 +03:00
<paramdef>…</paramdef>
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
2015-09-25 20:05:23 +03:00
</funcprototype>
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
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
doc: comma placement corrections and word order Set commas where there should be some. Some improvements to word order.
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
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
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
man: add sd_bus_message_new_call(3)
2018-07-26 21:00:36 +03:00
reversed with <function>sd_bus_path_decode()</function>. It is
doc: comma placement corrections and word order Set commas where there should be some. Some improvements to word order.
2014-05-08 03:28:45 +04:00
recommended to only use external identifiers that generally
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
require little escaping to be turned into valid bus path
doc: comma placement corrections and word order Set commas where there should be some. Some improvements to word order.
2014-05-08 03:28:45 +04:00
identifiers (for example, by sticking to a 7-bit ASCII character
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
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
doc: comma placement corrections and word order Set commas where there should be some. Some improvements to word order.
2014-05-08 03:28:45 +04:00
string is set to <constant>NULL</constant>. Otherwise, the
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
string following the prefix is unescaped and returned in the
external identifier string.</para>
doc: corrections to words and forms This patch exchange words which are inappropriate for a situation, deletes duplicated words, and adds particles where needed.
2014-05-08 03:28:44 +04:00
<para>The escaping used will replace all characters which are
doc: comma placement corrections and word order Set commas where there should be some. Some improvements to word order.
2014-05-08 03:28:45 +04:00
invalid in a bus object path by <literal>_</literal>, followed by a
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
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>
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
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
doc: correct punctuation and improve typography in documentation
2014-08-03 09:11:12 +04:00
takes a path template as argument and encodes multiple labels
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
2015-09-25 20:05:23 +03:00
according to its embedded directives. For each
<literal>%</literal> character found in the template, the caller
doc: correct punctuation and improve typography in documentation
2014-08-03 09:11:12 +04:00
must provide a string via varargs, which will be encoded and
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
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
doc: correct punctuation and improve typography in documentation
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
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
2015-09-25 20:05:23 +03:00
template, the caller must provide an output storage
doc: correct punctuation and improve typography in documentation
2014-08-03 09:11:12 +04:00
(<literal>char **</literal>) via varargs. The decoded label
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
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.
doc: correct orthography, word forms and missing/extraneous words
2014-08-03 09:11:37 +04:00
Furthermore, only a single directive is allowed per label.
sd-bus: add sd_bus_path_{encode,decode}_many() This introduces two new helpers alongside sd_bus_path_{encode,decode}(), which work similarly to their counterparts, but accept a format-string as input. This allows encoding and decoding multiple labels of a format string at the same time.
2015-09-25 20:05:23 +03:00
If <literal>NULL</literal> is passed as output storage, the
label is verified but not returned to the caller.</para>
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
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
doc: comma placement corrections and word order Set commas where there should be some. Some improvements to word order.
2014-05-08 03:28:45 +04:00
did not. If the prefix matched, the external identifier is returned
in the return parameter. If it did not match, NULL is returned in
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
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
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
by the caller.</para>
</refsect1>
man: include libsystemd-pkgconfig.xml in a few more man pages for some reason this was forgotten for a couple of sd_bus man pages, let's fix that.
2018-08-03 18:34:40 +03:00
<xi:include href="libsystemd-pkgconfig.xml" />
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
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>
bus: replace sd_bus_label_{escape,unescape}() by new sd_bus_path_{encode,decode}() The new calls work similarly, but enforce a that a common, fixed bus path prefix is used. This follows discussions with Simon McVittie on IRC that it should be a good idea to make sure that people don't use the escaping applied here too wildly as anything other than the last label of a bus path.
2014-03-11 22:03:50 +04:00
</para>
</refsect1>
</refentry>
Copy Permalink