man/sd_bus_message_append.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>sd_bus_message_append</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
   2     a.headerlink {
   3       color: #c60f0f;
   4       font-size: 0.8em;
   5       padding: 0 4px 0 4px;
   6       text-decoration: none;
   7       visibility: hidden;
   8     }
   9
  10     a.headerlink:hover {
  11       background-color: #c60f0f;
  12       color: white;
  13     }
  14
  15     h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
  16       visibility: visible;
  17     }
  18   </style><a href="index.html">Index </a>·
  19   <a href="systemd.directives.html">Directives </a>·
  20   <a href="../python-systemd/index.html">Python </a>·
  21   <a href="../libudev/index.html">libudev </a>·
  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"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>sd_bus_message_append — Attach parts of message based on a format string</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(</code></td><td>sd_bus_message *<var class="pdparam">m</var>, </td></tr><tr><td> </td><td>const char *<var class="pdparam">types</var>, </td></tr><tr><td> </td><td>...<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div></div><div class="refsect1"><a name="idm214183901008"></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</code> function appends
  23     a sequence of items to message <em class="parameter"><code>m</code></em>. The
  24     format string <em class="parameter"><code>types</code></em> describes the types of
  25     arguments that follow.</p><p>The format string is composed of the elements shown in the
  26     table below. It contains zero or more single "complete types".
  27     Each complete type may be one of the basic types or a fully
  28     described container type. A container type may be a structure, a
  29     variant type code, an array with its element type, or a dictionary
  30     with its entry type. The format string is
  31     <code class="constant">NUL</code>-terminated.</p><p>In case of a basic type, one argument of the corresponding
  32     type is expected.</p><p>A structure is denoted by a sequence of complete types
  33     between "<code class="literal">(</code>" and "<code class="literal">)</code>". This
  34     sequence cannot be empty — it must contain at least one type.
  35     Arguments corresponding to this nested sequence follow the same
  36     rules as if they were not nested.</p><p>A variant is denoted by "<code class="literal">v</code>". Correspoding
  37     arguments must include a format string denoting a complete type,
  38     and following that, arguments corresponding to the specified type.
  39     </p><p>An array is denoted by "<code class="literal">a</code>" followed by a
  40     complete type. Corresponding arguments must include the size of
  41     the array, and then repeated this number of times, arguments
  42     corresponding to the nested type.</p><p>A dictionary is an array of dictionary entries, denoted by
  43     "<code class="literal">a</code>" followed by a pair of complete types between
  44     "<code class="literal">{</code>" and "<code class="literal">}</code>". The first of those
  45     types must be a basic type. Corresponding arguments must include
  46     the size of the dictionary, and then repeated this number of
  47     times, arguments corresponding to each of the two nested
  48     types.</p><div class="table"><a name="idm214184578560"></a><p class="title"><b>Table 1. Item format specifiers</b></p><div class="table-contents"><table summary="Item format specifiers" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Specifier</th><th>Constant</th><th>Description</th><th>Size</th></tr></thead><tbody><tr><td>"<code class="literal">y</code>"</td><td><code class="constant">SD_BUS_TYPE_BYTE</code></td><td>unsigned interger</td><td>1 byte</td></tr><tr><td>"<code class="literal">b</code>"</td><td><code class="constant">SD_BUS_TYPE_BOOLEAN</code></td><td>boolean</td><td>4 bytes</td></tr><tr><td>"<code class="literal">n</code>"</td><td><code class="constant">SD_BUS_TYPE_INT16</code></td><td>signed integer</td><td>2 bytes</td></tr><tr><td>"<code class="literal">q</code>"</td><td><code class="constant">SD_BUS_TYPE_UINT16</code></td><td>unsigned integer</td><td>2 bytes</td></tr><tr><td>"<code class="literal">i</code>"</td><td><code class="constant">SD_BUS_TYPE_INT32</code></td><td>signed integer</td><td>4 bytes</td></tr><tr><td>"<code class="literal">u</code>"</td><td><code class="constant">SD_BUS_TYPE_UINT32</code></td><td>unsigned integer</td><td>4 bytes</td></tr><tr><td>"<code class="literal">x</code>"</td><td><code class="constant">SD_BUS_TYPE_INT64</code></td><td>signed integer</td><td>8 bytes</td></tr><tr><td>"<code class="literal">t</code>"</td><td><code class="constant">SD_BUS_TYPE_UINT64</code></td><td>unsigned integer</td><td>8 bytes</td></tr><tr><td>"<code class="literal">d</code>"</td><td><code class="constant">SD_BUS_TYPE_DOUBLE</code></td><td>floating-point</td><td>8 bytes</td></tr><tr><td>"<code class="literal">s</code>"</td><td><code class="constant">SD_BUS_TYPE_STRING</code></td><td>Unicode string</td><td>variable</td></tr><tr><td>"<code class="literal">o</code>"</td><td><code class="constant">SD_BUS_TYPE_OBJECT_PATH</code></td><td>object path</td><td>variable</td></tr><tr><td>"<code class="literal">g</code>"</td><td><code class="constant">SD_BUS_TYPE_SIGNATURE</code></td><td>signature</td><td>variable</td></tr><tr><td>"<code class="literal">h</code>"</td><td><code class="constant">SD_BUS_TYPE_UNIX_FD</code></td><td>UNIX file descriptor</td><td>4 bytes</td></tr><tr><td>"<code class="literal">a</code>"</td><td><code class="constant">SD_BUS_TYPE_ARRAY</code></td><td>array</td><td>determined by array type and size</td></tr><tr><td>"<code class="literal">v</code>"</td><td><code class="constant">SD_BUS_TYPE_VARIANT</code></td><td>variant</td><td>determined by the type argument</td></tr><tr><td>"<code class="literal">(</code>"</td><td><code class="constant">SD_BUS_TYPE_STRUCT_BEGIN</code></td><td>array start</td><td rowspan="2">determined by the nested types</td></tr><tr><td>"<code class="literal">)</code>"</td><td><code class="constant">SD_BUS_TYPE_STRUCT_END</code></td><td>array end</td></tr><tr><td>"<code class="literal">{</code>"</td><td><code class="constant">SD_BUS_TYPE_DICT_ENTRY_BEGIN</code></td><td>dictionary entry start</td><td rowspan="2">determined by the nested types</td></tr><tr><td>"<code class="literal">}</code>"</td><td><code class="constant">SD_BUS_TYPE_DICT_ENTRY_END</code></td><td>dictionary entry end</td></tr></tbody></table></div></div><br class="table-break"></div><div class="refsect1"><a name="idm214183669216"></a><h2 id="Types string grammar">Types string grammar<a class="headerlink" title="Permalink to this headline" href="#Types%20string%20grammar">¶</a></h2><pre class="programlisting">types ::= complete_type*
  49 complete_type ::= basic_type | variant | structure | array | dictionary
  50 basic_type ::= "y" | "n" | "q" | "u" | "i" | "x" | "t" | "d" |
  51                "b" | "h" |
  52                "s" | "o" | "g"
  53 variant ::= "v"
  54 structure ::= "(" complete_type+ ")"
  55 array ::= "a" complete_type
  56 dictionary ::= "a" "{" basic_type complete_type "}"
  57 </pre></div><div class="refsect1"><a name="idm214182869216"></a><h2 id="Examples">Examples<a class="headerlink" title="Permalink to this headline" href="#Examples">¶</a></h2><p>Append a single basic type (the string "<code class="literal">a string</code>"):
  58     </p><pre class="programlisting">sd_bus_message *m;
  59 ...
  60 sd_bus_message_append(m, "s", "a string");</pre><p>Append all types of integers:</p><pre class="programlisting">uint8_t y = 1;
  61 int16_t n = 2;
  62 uint16_t q = 3;
  63 int32_t i = 4;
  64 uint32_t u = 5;
  65 int32_t x = 6;
  66 uint32_t t = 7;
  67 double d = 8.0;
  68 sd_bus_message_append(m, "ynqiuxtd", y, n, q, i, u, x, t, d);</pre><p>Append a structure composed of string and a D-Bus path:</p><pre class="programlisting">sd_bus_message_append(m, "(so)", "a string", "/a/path");
  69 </pre><p>Append an array of UNIX file descriptors:</p><pre class="programlisting">sd_bus_message_append(m, "ah", 3, STDIN_FILENO, STDOUT_FILENO, STDERR_FILENO);
  70 </pre><p>Append a variant, with the real type "g" (signature),
  71      and value "sdbusisgood":</p><pre class="programlisting">sd_bus_message_append(m, "v", "g", "sdbusisgood");</pre><p>Append a dictionary containing the mapping {1=&gt;"a", 2=&gt;"b", 3=&gt;""}:
  72      </p><pre class="programlisting">sd_bus_message_append(m, "a{is}", 3, 1, "a", 2, "b", 3, NULL);
  73      </pre></div><div class="refsect1"><a name="idm214184952432"></a><h2 id="Return Value">Return Value<a class="headerlink" title="Permalink to this headline" href="#Return%20Value">¶</a></h2><p>On success, this call returns 0 or a positive
  74     integer. On failure, this call returns a negative
  75     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.
  76         </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.
  77         </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.
  78         </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.
  79         </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="idm214183757376"></a><h2 id="Notes">Notes<a class="headerlink" title="Permalink to this headline" href="#Notes">¶</a></h2><p><code class="function">sd_bus_open_user()</code> and other functions
  80     described here are available as a shared library, which can be
  81     compiled and linked to with the
  82     <code class="constant">libsystemd-bus</code> <a href="pkg-config.html"><span class="citerefentry"><span class="refentrytitle">pkg-config</span>(1)</span></a>
  83     file.</p></div><div class="refsect1"><a name="idm214183687248"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
  84       <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
  85       <a href="sd-bus.html"><span class="citerefentry"><span class="refentrytitle">sd-bus</span>(3)</span></a>,
  86       <a href="sd_bus_new.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_new</span>(3)</span></a>,
  87       <a href="sd_bus_ref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_ref</span>(3)</span></a>,
  88       <a href="sd_bus_unref.html"><span class="citerefentry"><span class="refentrytitle">sd_bus_unref</span>(3)</span></a>,
  89       <a href="ssh.html"><span class="citerefentry"><span class="refentrytitle">ssh</span>(1)</span></a>,
  90       <a href="systemd-machined.service.html"><span class="citerefentry"><span class="refentrytitle">systemd-machined.service</span>(8)</span></a>,
  91       <a href="machinectl.html"><span class="citerefentry"><span class="refentrytitle">machinectl</span>(1)</span></a>
  92     </p></div></div></body></html>