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