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