man/sd_bus_message_append_array.xml

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