man/sd_bus_message_append_array.xml

   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+ -->
   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>char <parameter>type</parameter></paramdef>
  61         <paramdef>size_t <parameter>size</parameter></paramdef>
  62         <paramdef>void **<parameter>ptr</parameter></paramdef>
  63       </funcprototype>
  64     </funcsynopsis>
  65   </refsynopsisdiv>
  66
  67   <refsect1>
  68     <title>Description</title>
  69
  70     <para>The <function>sd_bus_message_append_array()</function>
  71     function appends an array to a D-Bus message
  72     <parameter>m</parameter>. A container will be opened, the array
  73     contents appended, and the container closed. The parameter
  74     <parameter>type</parameter> determines how the pointer
  75     <parameter>p</parameter> is interpreted.
  76     <parameter>type</parameter> must be one of the "trivial" types
  77     <literal>y</literal>, <literal>n</literal>, <literal>q</literal>,
  78     <literal>i</literal>, <literal>u</literal>, <literal>x</literal>,
  79     <literal>t</literal>, <literal>d</literal> (but not
  80     <literal>b</literal>), as defined by the <ulink
  81     url="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
  82     Types</ulink> section of the D-Bus specification, and listed in
  83     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  84     Pointer <parameter>p</parameter> must point to an array of size
  85     <parameter>size</parameter> bytes containing items of the
  86     respective type. Size <parameter>size</parameter> must be a
  87     multiple of the size of the type <parameter>type</parameter>. As a
  88     special case, <parameter>p</parameter> may be
  89     <constant>NULL</constant>, if <parameter>size</parameter> is 0.
  90     The memory pointed to by <parameter>p</parameter> is copied into
  91     the memory area containing the message and stays in possession of
  92     the caller. The caller may hence freely change the data after this
  93     call without affecting the message the array was appended
  94     to.</para>
  95
  96     <para>The <function>sd_bus_message_append_array_memfd()</function>
  97     function appends an array of a trivial type to message
  98     <parameter>m</parameter>, similar to
  99     <function>sd_bus_message_append_array()</function>. The contents
 100     of the memory file descriptor <parameter>memfd</parameter>
 101     starting at the specified offset and of the specified size is
 102     used as the contents of the array. The offset and size must be a
 103     multiple of the size of the type
 104     <parameter>type</parameter>. However, as a special exception, if
 105     the offset is specified as zero and the size specified as
 106     UINT64_MAX the full memory file descriptor contents is used. The
 107     memory file descriptor is sealed by this call if it has not been
 108     sealed yet, and cannot be modified after this call. See
 109     <citerefentry
 110     project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 111     for details about memory file descriptors. Appending arrays with
 112     memory file descriptors enables efficient zero-copy data transfer,
 113     as the memory file descriptor may be passed as-is to the
 114     destination, without copying the memory in it to the destination
 115     process. Not all protocol transports support passing memory file
 116     descriptors between participants, in which case this call will
 117     automatically fall back to copying. Also, as memory file
 118     descriptor passing is inefficient for smaller amounts of data,
 119     copying might still be enforced even where memory file descriptor
 120     passing is supported.</para>
 121
 122     <para>The <function>sd_bus_message_append_array_iovec()</function>
 123     function appends an array of a trivial type to the message
 124     <parameter>m</parameter>, similar to
 125     <function>sd_bus_message_append_array()</function>. Contents of
 126     the I/O vector array <parameter>iov</parameter> are used as the
 127     contents of the array. The total size of
 128     <parameter>iov</parameter> payload (the sum of
 129     <structfield>iov_len</structfield> fields) must be a multiple of
 130     the size of the type <parameter>type</parameter>. The
 131     <parameter>iov</parameter> argument must point to
 132     <parameter>n</parameter> I/O vector structures. Each structure may
 133     have the <structname>iov_base</structname> field set, in which
 134     case the memory pointed to will be copied into the message, or
 135     unset (set to zero), in which case a block of zeros of length
 136     <structname>iov_len</structname> bytes will be inserted. The
 137     memory pointed at by <parameter>iov</parameter> may be changed
 138     after this call.</para>
 139
 140     <para>The <function>sd_bus_message_append_array_space()</function>
 141     function appends space for an array of a trivial type to message
 142     <parameter>m</parameter>.  It behaves the same as
 143     <function>sd_bus_message_append_array()</function>, but instead of
 144     copying items to the message, it returns a pointer to the
 145     destination area to the caller in pointer
 146     <parameter>p</parameter>. The caller should subsequently write the
 147     array contents to this memory. Modifications to the memory
 148     pointed to should only occur until the next operation on the bus
 149     message is invoked. Most importantly, the memory should not be
 150     altered anymore when another field has been added to the message
 151     or the message has been sealed.</para>
 152   </refsect1>
 153
 154   <refsect1>
 155     <title>Return Value</title>
 156
 157     <para>On success, these calls return 0 or a positive integer. On failure, they return a negative
 158     errno-style error code.</para>
 159
 160     <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
 161   </refsect1>
 162
 163   <xi:include href="libsystemd-pkgconfig.xml" />
 164
 165   <refsect1>
 166     <title>See Also</title>
 167
 168     <para>
 169       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 170       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 171       <citerefentry><refentrytitle>sd_bus_message_append</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 172       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 173       <citerefentry project='man-pages'><refentrytitle>memfd_create</refentrytitle><manvolnum>2</manvolnum></citerefentry>,
 174       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 175     </para>
 176   </refsect1>
 177
 178 </refentry>