projects / systemd.git / blame
| Commit | Line | Data |
|---|---|---|
| 60f067b4 JS |
1 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_bus_path_encode</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style> |
| 2 | a.headerlink { | |
| 3 | color: #c60f0f; | |
| 4 | font-size: 0.8em; | |
| 5 | padding: 0 4px 0 4px; | |
| 6 | text-decoration: none; | |
| 7 | visibility: hidden; | |
| 8 | } | |
| 9 | ||
| 10 | a.headerlink:hover { | |
| 11 | background-color: #c60f0f; | |
| 12 | color: white; | |
| 13 | } | |
| 14 | ||
| 15 | h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink { | |
| 16 | visibility: visible; | |
| 17 | } | |
| 18 | </style><a href="index.html">Index </a>· | |
| 19 | <a href="systemd.directives.html">Directives </a>· | |
| 20 | <a href="../python-systemd/index.html">Python </a>· | |
| 21 | <a href="../libudev/index.html">libudev </a>· | |
| e3bff60a | 22 | <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 220</span><hr><div class="refentry"><a name="sd_bus_path_encode"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_bus_path_encode, sd_bus_path_decode — Convert an external identifier into an object path and back</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include <systemd/sd-bus.h></pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_path_encode</b>(</code></td><td>const char *<var class="pdparam">prefix</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">external_id</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">ret_path</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sd_bus_path_decode</b>(</code></td><td>const char *<var class="pdparam">path</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">prefix</var>, </td></tr><tr><td> </td><td>char **<var class="pdparam">ret_external_id</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm139769710001680"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p><code class="function">sd_bus_path_encode()</code> and |
| 60f067b4 JS |
23 | <code class="function">sd_bus_path_decode()</code> convert external |
| 24 | identifier strings into object paths and back. These functions are | |
| 25 | useful to map application-specific string identifiers of any kind | |
| 26 | into bus object paths in a simple, reversible and safe way.</p><p><code class="function">sd_bus_path_encode()</code> takes a bus path | |
| 27 | prefix and an external identifier string as arguments, plus a | |
| 28 | place to store the returned bus path string. The bus path prefix | |
| 29 | must be a valid bus path, starting with a slash | |
| 30 | "<code class="literal">/</code>", and not ending in one. The external | |
| 31 | identifier string may be in any format, may be the empty string, | |
| 32 | and has no restrictions on the charset — however, it must | |
| 33 | always be <code class="constant">NUL</code>-terminated. The returned string | |
| 34 | will be the concatenation of the bus path prefix plus an escaped | |
| 35 | version of the external identifier string. This operation may be | |
| 36 | reversed with <code class="function">sd_bus_decode()</code>. It is | |
| 37 | recommended to only use external identifiers that generally | |
| 38 | require little escaping to be turned into valid bus path | |
| 39 | identifiers (for example, by sticking to a 7-bit ASCII character | |
| 40 | set), in order to ensure the resulting bus path is still short and | |
| 41 | easily processed.</p><p><code class="function">sd_bus_path_decode()</code> reverses the | |
| 42 | operation of <code class="function">sd_bus_path_encode()</code> and thus | |
| 43 | regenerates an external identifier string from a bus path. It | |
| 44 | takes a bus path and a prefix string, plus a place to store the | |
| 45 | returned external identifier string. If the bus path does not | |
| 46 | start with the specified prefix, 0 is returned and the returned | |
| 47 | string is set to <code class="constant">NULL</code>. Otherwise, the | |
| 48 | string following the prefix is unescaped and returned in the | |
| 49 | external identifier string.</p><p>The escaping used will replace all characters which are | |
| 50 | invalid in a bus object path by "<code class="literal">_</code>", followed by a | |
| 51 | hexadecimal value. As a special case, the empty string will be | |
| e3bff60a | 52 | replaced by a lone "<code class="literal">_</code>".</p></div><div class="refsect1"><a name="idm139769709991328"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p>On success, <code class="function">sd_bus_path_encode()</code> |
| 60f067b4 JS |
53 | returns positive or 0, and a valid bus path in the return |
| 54 | argument. On success, <code class="function">sd_bus_path_decode()</code> | |
| 55 | returns a positive value if the prefixed matched, or 0 if it | |
| 56 | did not. If the prefix matched, the external identifier is returned | |
| 57 | in the return parameter. If it did not match, NULL is returned in | |
| 58 | the return parameter. On failure, a negative errno-style error | |
| 59 | number is returned by either function. The returned strings must | |
| 60 | be | |
| 5eef597e | 61 | <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a>'d |
| e3bff60a | 62 | by the caller.</p></div><div class="refsect1"><a name="idm139769709987440"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p><code class="function">sd_bus_path_encode()</code> and |
| 60f067b4 JS |
63 | <code class="function">sd_bus_path_decode()</code> are available as a |
| 64 | shared library, which can be compiled and linked to with the | |
| 5eef597e | 65 | <code class="constant">libsystemd</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a> |
| e3bff60a | 66 | file.</p></div><div class="refsect1"><a name="idm139769709983664"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p> |
| 60f067b4 JS |
67 | <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>, |
| 68 | <a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>, | |
| 5eef597e | 69 | <a href="http://man7.org/linux/man-pages/man3/free.3.html"><span class="citerefentry"><span class="refentrytitle">free</span>(3)</span></a> |
| 60f067b4 | 70 | </p></div></div></body></html> |