1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="sd_bus_message_append_array"
7          xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>sd_bus_message_append_array</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>sd_bus_message_append_array</refentrytitle>
16    <manvolnum>3</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>sd_bus_message_append_array</refname>
21    <refname>sd_bus_message_append_array_memfd</refname>
22    <refname>sd_bus_message_append_array_iovec</refname>
23    <refname>sd_bus_message_append_array_space</refname>
24
25    <refpurpose>Append an array of fields to a D-Bus
26    message</refpurpose>
27  </refnamediv>
28
29  <refsynopsisdiv>
30    <funcsynopsis>
31      <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
32
33      <funcprototype>
34        <funcdef>int sd_bus_message_append_array</funcdef>
35        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
36        <paramdef>char <parameter>type</parameter></paramdef>
37        <paramdef>void *<parameter>ptr</parameter></paramdef>
38        <paramdef>size_t <parameter>size</parameter></paramdef>
39      </funcprototype>
40
41      <funcprototype>
42        <funcdef>int sd_bus_message_append_array_memfd</funcdef>
43        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
44        <paramdef>char <parameter>type</parameter></paramdef>
45        <paramdef>int <parameter>memfd</parameter></paramdef>
46        <paramdef>uint64_t <parameter>offset</parameter></paramdef>
47        <paramdef>uint64_t <parameter>size</parameter></paramdef>
48      </funcprototype>
49
50      <funcprototype>
51        <funcdef>int sd_bus_message_append_array_iovec</funcdef>
52        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
53        <paramdef>char <parameter>type</parameter></paramdef>
54        <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
55        <paramdef>unsigned <parameter>n</parameter></paramdef>
56      </funcprototype>
57
58      <funcprototype>
59        <funcdef>int sd_bus_message_append_array_space</funcdef>
60        <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
61        <paramdef>char <parameter>type</parameter></paramdef>
62        <paramdef>size_t <parameter>size</parameter></paramdef>
63        <paramdef>void **<parameter>ptr</parameter></paramdef>
64      </funcprototype>
65    </funcsynopsis>
66  </refsynopsisdiv>
67
68  <refsect1>
69    <title>Description</title>
70
71    <para>The <function>sd_bus_message_append_array()</function>
72    function appends an array to a D-Bus message
73    <parameter>m</parameter>. A container will be opened, the array
74    contents appended, and the container closed. The parameter
75    <parameter>type</parameter> determines how the pointer
76    <parameter>p</parameter> is interpreted.
77    <parameter>type</parameter> must be one of the "trivial" types
78    <literal>y</literal>, <literal>n</literal>, <literal>q</literal>,
79    <literal>i</literal>, <literal>u</literal>, <literal>x</literal>,
80    <literal>t</literal>, <literal>d</literal> (but not
81    <literal>b</literal>), as defined by the <ulink
82    url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
83    Types</ulink> section of the D-Bus specification, and listed in
84    <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
85    Pointer <parameter>p</parameter> must point to an array of size
86    <parameter>size</parameter> bytes containing items of the
87    respective type. Size <parameter>size</parameter> must be a
88    multiple of the size of the type <parameter>type</parameter>. As a
89    special case, <parameter>p</parameter> may be
90    <constant>NULL</constant>, if <parameter>size</parameter> is 0.
91    The memory pointed to by <parameter>p</parameter> is copied into
92    the memory area containing the message and stays in possession of
93    the caller. The caller may hence freely change the data after this
94    call without affecting the message the array was appended
95    to.</para>
96
97    <para>The <function>sd_bus_message_append_array_memfd()</function>
98    function appends an array of a trivial type to message
99    <parameter>m</parameter>, similar to
100    <function>sd_bus_message_append_array()</function>. The contents
101    of the memory file descriptor <parameter>memfd</parameter>
102    starting at the specified offset and of the specified size is
103    used as the contents of the array. The offset and size must be a
104    multiple of the size of the type
105    <parameter>type</parameter>. However, as a special exception, if
106    the offset is specified as zero and the size specified as
107    UINT64_MAX the full memory file descriptor contents is used. The
108    memory file descriptor is sealed by this call if it has not been
109    sealed yet, and cannot be modified after this call. See
110    <citerefentry
111    project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
112    for details about memory file descriptors. Appending arrays with
113    memory file descriptors enables efficient zero-copy data transfer,
114    as the memory file descriptor may be passed as-is to the
115    destination, without copying the memory in it to the destination
116    process. Not all protocol transports support passing memory file
117    descriptors between participants, in which case this call will
118    automatically fall back to copying. Also, as memory file
119    descriptor passing is inefficient for smaller amounts of data,
120    copying might still be enforced even where memory file descriptor
121    passing is supported.</para>
122
123    <para>The <function>sd_bus_message_append_array_iovec()</function>
124    function appends an array of a trivial type to the message
125    <parameter>m</parameter>, similar to
126    <function>sd_bus_message_append_array()</function>. Contents of
127    the I/O vector array <parameter>iov</parameter> are used as the
128    contents of the array. The total size of
129    <parameter>iov</parameter> payload (the sum of
130    <structfield>iov_len</structfield> fields) must be a multiple of
131    the size of the type <parameter>type</parameter>. The
132    <parameter>iov</parameter> argument must point to
133    <parameter>n</parameter> I/O vector structures. Each structure may
134    have the <structname>iov_base</structname> field set, in which
135    case the memory pointed to will be copied into the message, or
136    unset (set to zero), in which case a block of zeros of length
137    <structname>iov_len</structname> bytes will be inserted. The
138    memory pointed at by <parameter>iov</parameter> may be changed
139    after this call.</para>
140
141    <para>The <function>sd_bus_message_append_array_space()</function>
142    function appends space for an array of a trivial type to message
143    <parameter>m</parameter>.  It behaves the same as
144    <function>sd_bus_message_append_array()</function>, but instead of
145    copying items to the message, it returns a pointer to the
146    destination area to the caller in pointer
147    <parameter>p</parameter>. The caller should subsequently write the
148    array contents to this memory. Modifications to the memory
149    pointed to should only occur until the next operation on the bus
150    message is invoked. Most importantly, the memory should not be
151    altered anymore when another field has been added to the message
152    or the message has been sealed.</para>
153  </refsect1>
154
155  <refsect1>
156    <title>Return Value</title>
157
158    <para>On success, these calls return 0 or a positive integer. On failure, they return a negative
159    errno-style error code.</para>
160
161    <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
162  </refsect1>
163
164  <xi:include href="libsystemd-pkgconfig.xml" />
165
166  <refsect1>
167    <title>See Also</title>
168
169    <para>
170      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
171      <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
172      <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
173      <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
174      <citerefentry project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
175      <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
176    </para>
177  </refsect1>
178
179</refentry>
180