1 <html><head><meta http-equiv=
"Content-Type" content=
"text/html; charset=UTF-8"><title>sd_bus_message_append_array
</title><meta name=
"generator" content=
"DocBook XSL Stylesheets V1.78.1"></head><body bgcolor=
"white" text=
"black" link=
"#0000FF" vlink=
"#840084" alink=
"#0000FF"><style>
11 background-color: #c60f0f;
15 h1:hover
> a.headerlink, h2:hover
> a.headerlink, h3:hover
> a.headerlink, dt:hover
> a.headerlink {
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>·
22 <a href=
"../libudev/index.html">gudev
</a><span style=
"float:right">systemd
219</span><hr><div class=
"refentry"><a name=
"sd_bus_message_append_array"></a><div class=
"titlepage"></div><div class=
"refnamediv"><h2>Name
</h2><p>sd_bus_message_append_array, sd_bus_message_append_array_memfd, sd_bus_message_append_array_iovec, sd_bus_message_append_array_space — Attach an array of items to a message
</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_array(
</code></td><td>sd_bus_message *
<var class=
"pdparam">m
</var>,
</td></tr><tr><td> </td><td>char
<var class=
"pdparam">type
</var>,
</td></tr><tr><td> </td><td>char void *
<var class=
"pdparam">ptr
</var>,
</td></tr><tr><td> </td><td>size_t
<var class=
"pdparam">size
</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 sd_bus_message_append_array_memfd(
</code></td><td>sd_bus_message *
<var class=
"pdparam">m
</var>,
</td></tr><tr><td> </td><td>char
<var class=
"pdparam">type
</var>,
</td></tr><tr><td> </td><td>int
<var class=
"pdparam">memfd
</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 sd_bus_message_append_array_iovec(
</code></td><td>sd_bus_message *
<var class=
"pdparam">m
</var>,
</td></tr><tr><td> </td><td>char
<var class=
"pdparam">type
</var>,
</td></tr><tr><td> </td><td>const struct iovec *
<var class=
"pdparam">iov
</var>,
</td></tr><tr><td> </td><td>unsigned
<var class=
"pdparam">n
</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 sd_bus_message_append_array_space(
</code></td><td>char
<var class=
"pdparam">type
</var>,
</td></tr><tr><td> </td><td>size_t
<var class=
"pdparam">size
</var>,
</td></tr><tr><td> </td><td>char void **
<var class=
"pdparam">ptr
</var><code>)
</code>;
</td></tr></table><div class=
"funcprototype-spacer"> </div></div></div><div class=
"refsect1"><a name=
"idm139649241721696"></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_array
</code> functionc
23 appends items to message
<em class=
"parameter"><code>m
</code></em> as the single
24 array. A container will be opened, items appended, and the
25 container closed. Parameter
<em class=
"parameter"><code>type
</code></em> determines
26 how pointer
<em class=
"parameter"><code>p
</code></em> is interpreted.
27 <em class=
"parameter"><code>type
</code></em> must be one of the
"trivial" types
28 "<code class="literal
">y</code>",
"<code class="literal
">n</code>",
"<code class="literal
">q</code>",
29 "<code class="literal
">i</code>",
"<code class="literal
">u</code>",
"<code class="literal
">x</code>",
30 "<code class="literal
">t</code>",
"<code class="literal
">d</code>" (but not
31 "<code class="literal
">b</code>"), as defined by the
32 <a class=
"ulink" href=
"http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types" target=
"_top">Basic Types
</a>
33 section of the D-Bus specification, and listed in
34 <a href=
"sd_bus_message_append_basic.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_bus_message_append_basic
</span>(
3)
</span></a>.
35 Pointer
<em class=
"parameter"><code>p
</code></em> must point to an array of size
36 <em class=
"parameter"><code>size
</code></em> bytes containing items of the
37 respective type. Size
<em class=
"parameter"><code>size
</code></em> must be a
38 multiple of the size of the type
<em class=
"parameter"><code>type
</code></em>. As a
39 special case,
<em class=
"parameter"><code>p
</code></em> may be
40 <code class=
"constant">NULL
</code>, if
<em class=
"parameter"><code>size
</code></em> is
0.
41 </p><p>The memory pointed at by
<em class=
"parameter"><code>p
</code></em> is copied
42 into the memory area containing the message and may be changed
43 after this call.
</p><p>The
44 <code class=
"function">sd_bus_message_append_array_memfd
</code> function appends
45 items to message
<em class=
"parameter"><code>m
</code></em>, similarly to
46 <code class=
"function">sd_bus_message_append_array
</code>. Contents of the
47 memory file descriptor
<em class=
"parameter"><code>memfd
</code></em> are used as
48 the contents of the array. Their size must be a multiple of the
49 size of the type
<em class=
"parameter"><code>type
</code></em>.
</p><p>The descriptor specified with
<em class=
"parameter"><code>memfd
</code></em>
50 will be sealed and cannot be modified after this call.
</p><p>The
51 <code class=
"function">sd_bus_message_append_array_iovec
</code> function appends
52 items to message
<em class=
"parameter"><code>m
</code></em>, similarly to
53 <code class=
"function">sd_bus_message_append_array
</code>. Contents of the
54 iovec
<em class=
"parameter"><code>iov
</code></em> are used as the contents of the
55 array. The total size of
<em class=
"parameter"><code>iov
</code></em> payload (the
56 sum of
<em class=
"structfield"><code>iov_len
</code></em> fields) must be a multiple
57 of the size of the type
<em class=
"parameter"><code>type
</code></em>.
</p><p>The
<em class=
"parameter"><code>iov
</code></em> argument must point to
58 <em class=
"parameter"><code>n
</code></em> <span class=
"structname">struct iovec
</span>
59 structures. Each structure may have the
60 <span class=
"structname">iov_base
</span> field set, in which case the
61 memory pointed to will be copied into the message, or unset, in
62 which case a block of zeros of length
63 <span class=
"structname">iov_len
</span> bytes will be inserted. The
64 memory pointed at by
<em class=
"parameter"><code>iov
</code></em> may be changed
65 after this call.
</p><p>The
66 <code class=
"function">sd_bus_message_append_array_space
</code> function appends
67 space for an array of items to message
<em class=
"parameter"><code>m
</code></em>.
68 It behaves the same as
69 <code class=
"function">sd_bus_message_append_array
</code>, but instead
70 of copying items to the message, it returns a pointer to the
71 destination area to the caller in pointer
<em class=
"parameter"><code>p
</code></em>.
72 </p></div><div class=
"refsect1"><a name=
"idm139649241678720"></a><h2 id=
"Return Value">Return Value
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Return%20Value">¶
</a></h2><p>On success, these calls return
0 or a positive integer. On
73 failure, they 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.
74 </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.
75 </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.
76 </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.
77 </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=
"idm139649236764048"></a><h2 id=
"Notes">Notes
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#Notes">¶
</a></h2><p><code class=
"function">sd_bus_append_array()
</code> and other
78 functions described here are available as a shared library, which
79 can be compiled and linked to with the
80 <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>
81 file.
</p></div><div class=
"refsect1"><a name=
"idm139649236760864"></a><h2 id=
"See Also">See Also
<a class=
"headerlink" title=
"Permalink to this headline" href=
"#See%20Also">¶
</a></h2><p>
82 <a href=
"systemd.html"><span class=
"citerefentry"><span class=
"refentrytitle">systemd
</span>(
1)
</span></a>,
83 <a href=
"sd-bus.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd-bus
</span>(
3)
</span></a>,
84 <a href=
"sd_bus_message_append.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_bus_message_append
</span>(
3)
</span></a>,
85 <a href=
"sd_bus_message_append_basic.html"><span class=
"citerefentry"><span class=
"refentrytitle">sd_bus_message_append_basic
</span>(
3)
</span></a>,
86 <a class=
"ulink" href=
"http://dbus.freedesktop.org/doc/dbus-specification.html" target=
"_top">The D-Bus specification
</a>
87 </p></div></div></body></html>