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