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-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>const 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="https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
  83     D-Bus 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="https://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 176     </para>
 177   </refsect1>
 178
 179 </refentry>