1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_bus_message_append</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
a.headerlink {
color: #c60f0f;
font-size: 0.8em;
padding: 0 4px 0 4px;
text-decoration: none;
visibility: hidden;
}
a.headerlink:hover {
background-color: #c60f0f;
color: white;
}
h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
visibility: visible;
}
</style><a href="index.html">Index </a>·
<a href="systemd.directives.html">Directives </a>·
<a href="../python-systemd/index.html">Python </a>·
<span style="float:right">systemd 221</span><hr><div class="refentry"><a name="sd_bus_message_append"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_bus_message_append — Attach parts of message based on a format string</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 sd_bus_message_append(</code></td><td>sd_bus_message *<var class="pdparam">m</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">types</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm46934141235600"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>The <code class="function">sd_bus_message_append</code> function appends
a sequence of items to message <em class="parameter"><code>m</code></em>. The
format string <em class="parameter"><code>types</code></em> describes the types of
arguments that follow.</p><p>The format string is composed of the elements shown in the
table below. It contains zero or more single "complete types".
Each complete type may be one of the basic types or a fully
described container type. A container type may be a structure, a
variant type code, an array with its element type, or a dictionary
with its entry type. The format string is
<code class="constant">NUL</code>-terminated.</p><p>In case of a basic type, one argument of the corresponding
type is expected.</p><p>A structure is denoted by a sequence of complete types
between "<code class="literal">(</code>" and "<code class="literal">)</code>". This
sequence cannot be empty — it must contain at least one type.
Arguments corresponding to this nested sequence follow the same
rules as if they were not nested.</p><p>A variant is denoted by "<code class="literal">v</code>". Corresponding
arguments must include a format string denoting a complete type,
and following that, arguments corresponding to the specified type.
</p><p>An array is denoted by "<code class="literal">a</code>" followed by a
complete type. Corresponding arguments must include the size of
the array, and then repeated this number of times, arguments
corresponding to the nested type.</p><p>A dictionary is an array of dictionary entries, denoted by
"<code class="literal">a</code>" followed by a pair of complete types between
"<code class="literal">{</code>" and "<code class="literal">}</code>". The first of those
types must be a basic type. Corresponding arguments must include
the size of the dictionary, and then repeated this number of
times, arguments corresponding to each of the two nested
types.</p><div class="table"><a name="idm46934136323344"></a><p class="title"><b>Table 1. Item format specifiers</b></p><div class="table-contents"><table summary="Item format specifiers" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Specifier</th><th>Constant</th><th>Description</th><th>Size</th></tr></thead><tbody><tr><td>"<code class="literal">y</code>"</td><td><code class="constant">SD_BUS_TYPE_BYTE</code></td><td>unsigned integer</td><td>1 byte</td></tr><tr><td>"<code class="literal">b</code>"</td><td><code class="constant">SD_BUS_TYPE_BOOLEAN</code></td><td>boolean</td><td>4 bytes</td></tr><tr><td>"<code class="literal">n</code>"</td><td><code class="constant">SD_BUS_TYPE_INT16</code></td><td>signed integer</td><td>2 bytes</td></tr><tr><td>"<code class="literal">q</code>"</td><td><code class="constant">SD_BUS_TYPE_UINT16</code></td><td>unsigned integer</td><td>2 bytes</td></tr><tr><td>"<code class="literal">i</code>"</td><td><code class="constant">SD_BUS_TYPE_INT32</code></td><td>signed integer</td><td>4 bytes</td></tr><tr><td>"<code class="literal">u</code>"</td><td><code class="constant">SD_BUS_TYPE_UINT32</code></td><td>unsigned integer</td><td>4 bytes</td></tr><tr><td>"<code class="literal">x</code>"</td><td><code class="constant">SD_BUS_TYPE_INT64</code></td><td>signed integer</td><td>8 bytes</td></tr><tr><td>"<code class="literal">t</code>"</td><td><code class="constant">SD_BUS_TYPE_UINT64</code></td><td>unsigned integer</td><td>8 bytes</td></tr><tr><td>"<code class="literal">d</code>"</td><td><code class="constant">SD_BUS_TYPE_DOUBLE</code></td><td>floating-point</td><td>8 bytes</td></tr><tr><td>"<code class="literal">s</code>"</td><td><code class="constant">SD_BUS_TYPE_STRING</code></td><td>Unicode string</td><td>variable</td></tr><tr><td>"<code class="literal">o</code>"</td><td><code class="constant">SD_BUS_TYPE_OBJECT_PATH</code></td><td>object path</td><td>variable</td></tr><tr><td>"<code class="literal">g</code>"</td><td><code class="constant">SD_BUS_TYPE_SIGNATURE</code></td><td>signature</td><td>variable</td></tr><tr><td>"<code class="literal">h</code>"</td><td><code class="constant">SD_BUS_TYPE_UNIX_FD</code></td><td>UNIX file descriptor</td><td>4 bytes</td></tr><tr><td>"<code class="literal">a</code>"</td><td><code class="constant">SD_BUS_TYPE_ARRAY</code></td><td>array</td><td>determined by array type and size</td></tr><tr><td>"<code class="literal">v</code>"</td><td><code class="constant">SD_BUS_TYPE_VARIANT</code></td><td>variant</td><td>determined by the type argument</td></tr><tr><td>"<code class="literal">(</code>"</td><td><code class="constant">SD_BUS_TYPE_STRUCT_BEGIN</code></td><td>array start</td><td rowspan="2">determined by the nested types</td></tr><tr><td>"<code class="literal">)</code>"</td><td><code class="constant">SD_BUS_TYPE_STRUCT_END</code></td><td>array end</td></tr><tr><td>"<code class="literal">{</code>"</td><td><code class="constant">SD_BUS_TYPE_DICT_ENTRY_BEGIN</code></td><td>dictionary entry start</td><td rowspan="2">determined by the nested types</td></tr><tr><td>"<code class="literal">}</code>"</td><td><code class="constant">SD_BUS_TYPE_DICT_ENTRY_END</code></td><td>dictionary entry end</td></tr></tbody></table></div></div><br class="table-break"></div><div class="refsect1"><a name="idm46934136305024"></a><h2 id="Types string grammar">Types string grammar<a class="headerlink" title="Permalink to this headline" href="#Types%20string%20grammar">¶</a></h2><pre class="programlisting">types ::= complete_type*
complete_type ::= basic_type | variant | structure | array | dictionary
basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
"b" | "h" |
"s" | "o" | "g"
variant ::= "v"
structure ::= "(" complete_type+ ")"
array ::= "a" complete_type
dictionary ::= "a" "{" basic_type complete_type "}"
</pre></div><div class="refsect1"><a name="idm46934136303264"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><p>Append a single basic type (the string "<code class="literal">a string</code>"):
</p><pre class="programlisting">sd_bus_message *m;
...
sd_bus_message_append(m, "s", "a string");</pre><p>Append all types of integers:</p><pre class="programlisting">uint8_t y = 1;
int16_t n = 2;
uint16_t q = 3;
int32_t i = 4;
uint32_t u = 5;
int32_t x = 6;
uint32_t t = 7;
double d = 8.0;
sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</pre><p>Append a structure composed of string and a D-Bus path:</p><pre class="programlisting">sd_bus_message_append(m, "(so)", "a string", "/a/path");
</pre><p>Append an array of UNIX file descriptors:</p><pre class="programlisting">sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
</pre><p>Append a variant, with the real type "g" (signature),
and value "sdbusisgood":</p><pre class="programlisting">sd_bus_message_append(m, "v", "g", "sdbusisgood");</pre><p>Append a dictionary containing the mapping {1=>"a", 2=>"b", 3=>""}:
</p><pre class="programlisting">sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
</pre></div><div class="refsect1"><a name="idm46934136295328"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p>On success, this call returns 0 or a positive
integer. On failure, this call returns a negative
errno-style error code.</p></div><div class="refsect1"><a name="errors"></a><h2 id="Errors">Errors<a class="headerlink" title="Permalink to this headline" href="#Errors">¶</a></h2><p>Returned errors may indicate the following problems:</p><div class="variablelist"><dl class="variablelist"><dt id="-EINVAL"><span class="term"><code class="constant">-EINVAL</code></span><a class="headerlink" title="Permalink to this term" href="#-EINVAL">¶</a></dt><dd><p>Specified parameter is invalid.
</p></dd><dt id="-EPERM"><span class="term"><code class="constant">-EPERM</code></span><a class="headerlink" title="Permalink to this term" href="#-EPERM">¶</a></dt><dd><p>Message has been sealed.
</p></dd><dt id="-ESTALE"><span class="term"><code class="constant">-ESTALE</code></span><a class="headerlink" title="Permalink to this term" href="#-ESTALE">¶</a></dt><dd><p>Message is in invalid state.
</p></dd><dt id="-ENXIO"><span class="term"><code class="constant">-ENXIO</code></span><a class="headerlink" title="Permalink to this term" href="#-ENXIO">¶</a></dt><dd><p>Message cannot be appended to.
</p></dd><dt id="-ENOMEM"><span class="term"><code class="constant">-ENOMEM</code></span><a class="headerlink" title="Permalink to this term" href="#-ENOMEM">¶</a></dt><dd><p>Memory allocation failed.</p></dd></dl></div></div><div class="refsect1"><a name="idm46934136293296"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p><code class="function">sd_bus_open_user()</code> and other functions
described here are available as a shared library, which can be
compiled and linked to with the
<code class="constant">libsystemd-bus</code> <a href="http://linux.die.net/man/1/pkg-config"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
file.</p></div><div class="refsect1"><a name="idm46934136290112"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
<a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
<a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>,
<a href="sd_bus_new.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_new</span>(3)</span></a>,
<a href="sd_bus_ref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_ref</span>(3)</span></a>,
<a href="sd_bus_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_unref</span>(3)</span></a>,
<a href="http://linux.die.net/man/1/ssh"><span class="citerefentry"><span class="refentrytitle">ssh</span>(1)</span></a>,
<a href="systemd-machined.service.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined.service</span>(8)</span></a>,
<a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>
</p></div></div></body></html>
|
