sd_bus_message_append_array_iovec.html 10.3 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_bus_message_append_array</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><a href="index.html">Index </a>·
  <a href="systemd.directives.html">Directives </a>·
  <a href="../python-systemd/index.html">Python </a>·
  <a href="../libudev/index.html">libudev </a>·
Michael Biebl's avatar
Michael Biebl committed
22
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 215</span><hr><div class="refentry"><a name="sd_bus_message_append_array"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_bus_message_append_array, sd_bus_message_append_array_memfd, sd_bus_message_append_array_iovec, sd_bus_message_append_array_space — Attach an array of items to a message</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;systemd/sd-bus.h&gt;</pre><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int sd_bus_message_append_array(</code></td><td>sd_bus_message *<var class="pdparam">m</var>, </td></tr><tr><td> </td><td>char <var class="pdparam">type</var>, </td></tr><tr><td> </td><td>char void *<var class="pdparam">ptr</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int sd_bus_message_append_array_memfd(</code></td><td>sd_bus_message *<var class="pdparam">m</var>, </td></tr><tr><td> </td><td>char <var class="pdparam">type</var>, </td></tr><tr><td> </td><td>sd_memfd *<var class="pdparam">memfd</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int sd_bus_message_append_array_iovec(</code></td><td>sd_bus_message *<var class="pdparam">m</var>, </td></tr><tr><td> </td><td>char <var class="pdparam">type</var>, </td></tr><tr><td> </td><td>const struct iovec *<var class="pdparam">iov</var>, </td></tr><tr><td> </td><td>unsigned <var class="pdparam">n</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int sd_bus_message_append_array_space(</code></td><td>char <var class="pdparam">type</var>, </td></tr><tr><td> </td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td> </td><td>char void **<var class="pdparam">ptr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm214170011040"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description"></a></h2><p>The <code class="function">sd_bus_message_append_array</code> functionc
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71
    appends items to message <em class="parameter"><code>m</code></em> as the single
    array. A container will be opened, items appended, and the
    container closed. Parameter <em class="parameter"><code>type</code></em> determines
    how pointer <em class="parameter"><code>p</code></em> is interpreted.
    <em class="parameter"><code>type</code></em> must be one of the "trivial" types
    "<code class="literal">y</code>", "<code class="literal">n</code>", "<code class="literal">q</code>",
    "<code class="literal">i</code>", "<code class="literal">u</code>", "<code class="literal">x</code>",
    "<code class="literal">t</code>", "<code class="literal">d</code>" (but not
    "<code class="literal">b</code>"), as defined by the
    <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html#basic-types" target="_top">Basic Types</a>
    section of the D-Bus specification, and listed in
    <a href="sd_bus_message_append_basic.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_message_append_basic</span>(3)</span></a>.
    Pointer <em class="parameter"><code>p</code></em> must point to an array of of size
    <em class="parameter"><code>size</code></em> bytes containing items of the
    respective type. Size <em class="parameter"><code>size</code></em> must be a
    multiple of the size of the type <em class="parameter"><code>type</code></em>. As a
    special case, <em class="parameter"><code>p</code></em> may be
    <code class="constant">NULL</code>, if <em class="parameter"><code>size</code></em> is 0.
    </p><p>The memory pointed at by <em class="parameter"><code>p</code></em> is copied
    into the memory area containing the message and may be changed
    after this call.</p><p>The
    <code class="function">sd_bus_message_append_array_memfd</code> function appends
    items to message <em class="parameter"><code>m</code></em>, similarly to
    <code class="function">sd_bus_message_append_array</code>. Contents of the
    memory file descriptor <em class="parameter"><code>memfd</code></em> are used as
    the contents of the array. Their size must be a multiple of the
    size of the type <em class="parameter"><code>type</code></em>.</p><p>The descriptor specified with <em class="parameter"><code>memfd</code></em>
    will be sealed and cannot be modified after this call.</p><p>The
    <code class="function">sd_bus_message_append_array_iovec</code> function appends
    items to message <em class="parameter"><code>m</code></em>, similarly to
    <code class="function">sd_bus_message_append_array</code>. Contents of the
    iovec <em class="parameter"><code>iov</code></em> are used as the contents of the
    array. The total size of <em class="parameter"><code>iov</code></em> payload (the
    sum of <em class="structfield"><code>iov_len</code></em> fields) must be a multiple
    of the size of the type <em class="parameter"><code>type</code></em>.</p><p>The <em class="parameter"><code>iov</code></em> argument must point to
    <em class="parameter"><code>n</code></em> <span class="structname">struct iovec</span>
    structures. Each structure may have the
    <span class="structname">iov_base</span> field set, in which case the
    memory pointed to will be copied into the message, or unset, in
    which case a block of zeros of length
    <span class="structname">iov_len</span> bytes will be inserted. The
    memory pointed at by <em class="parameter"><code>iov</code></em> may be changed
    after this call.</p><p>The
    <code class="function">sd_bus_message_append_array_space</code> function appends
    space for an array of items to message <em class="parameter"><code>m</code></em>.
    It behaves the same as
    <code class="function">sd_bus_message_append_array</code>, but instead
    of copying items to the message, it returns a pointer to the
    destination area to the caller in pointer <em class="parameter"><code>p</code></em>.
Michael Biebl's avatar
Michael Biebl committed
72
    </p></div><div class="refsect1"><a name="idm214169563840"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value"></a></h2><p>On success, these calls return 0 or a positive integer. On
73 74 75 76
    failure, they returns a negative errno-style error code.</p></div><div class="refsect1"><a name="errors"></a><h2 id="Errors">Errors<a class="headerlink" title="Permalink to this headline" href="#Errors"></a></h2><p>Returned errors may indicate the following problems:</p><div class="variablelist"><dl class="variablelist"><dt id="-EINVAL"><span class="term"><code class="varname">-EINVAL</code></span><a class="headerlink" title="Permalink to this term" href="#-EINVAL"></a></dt><dd><p>Specified parameter is invalid.
        </p></dd><dt id="-EPERM"><span class="term"><code class="varname">-EPERM</code></span><a class="headerlink" title="Permalink to this term" href="#-EPERM"></a></dt><dd><p>Message has been sealed.
        </p></dd><dt id="-ESTALE"><span class="term"><code class="varname">-ESTALE</code></span><a class="headerlink" title="Permalink to this term" href="#-ESTALE"></a></dt><dd><p>Message is in invalid state.
        </p></dd><dt id="-ENXIO"><span class="term"><code class="varname">-ENXIO</code></span><a class="headerlink" title="Permalink to this term" href="#-ENXIO"></a></dt><dd><p>Message cannot be appended to.
Michael Biebl's avatar
Michael Biebl committed
77
        </p></dd><dt id="-ENOMEM"><span class="term"><code class="varname">-ENOMEM</code></span><a class="headerlink" title="Permalink to this term" href="#-ENOMEM"></a></dt><dd><p>Memory allocation failed.</p></dd></dl></div></div><div class="refsect1"><a name="idm214171075696"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes"></a></h2><p><code class="function">sd_bus_append_array()</code> and other
78 79 80
    functions described here are available as a shared library, which
    can be compiled and linked to with the
    <code class="constant">libsystemd</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
Michael Biebl's avatar
Michael Biebl committed
81
    file.</p></div><div class="refsect1"><a name="idm214169857648"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also"></a></h2><p>
82 83 84 85 86 87
      <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
      <a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>,
      <a href="sd_bus_message_append.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_message_append</span>(3)</span></a>,
      <a href="sd_bus_message_append_basic.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_message_append_basic</span>(3)</span></a>,
      <a class="ulink" href="http://dbus.freedesktop.org/doc/dbus-specification.html" target="_top">The D-Bus specification</a>
    </p></div></div></body></html>