man/sd_bus_message_append_string_memfd.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_string_memfd"
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>sd_bus_message_append_string_memfd</title>
  14     <productname>elogind</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>sd_bus_message_append_string_memfd</refentrytitle>
  19     <manvolnum>3</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>sd_bus_message_append_string_memfd</refname>
  24     <refname>sd_bus_message_append_string_iovec</refname>
  25     <refname>sd_bus_message_append_string_space</refname>
  26
  27     <refpurpose>Attach a string to a message</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <funcsynopsis>
  32       <funcsynopsisinfo>#include &lt;elogind/sd-bus.h&gt;</funcsynopsisinfo>
  33
  34       <funcprototype>
  35         <funcdef>int sd_bus_message_append_string_memfd</funcdef>
  36         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  37         <paramdef>int <parameter>memfd</parameter></paramdef>
  38       </funcprototype>
  39
  40       <funcprototype>
  41         <funcdef>int sd_bus_message_append_string_iovec</funcdef>
  42         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  43         <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
  44         <paramdef>unsigned <parameter>n</parameter></paramdef>
  45       </funcprototype>
  46
  47       <funcprototype>
  48         <funcdef>int sd_bus_message_append_string_space</funcdef>
  49         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  50         <paramdef>size_t <parameter>size</parameter></paramdef>
  51         <paramdef>char **<parameter>s</parameter></paramdef>
  52       </funcprototype>
  53     </funcsynopsis>
  54   </refsynopsisdiv>
  55
  56   <refsect1>
  57     <title>Description</title>
  58
  59     <para>The functions
  60     <function>sd_bus_message_append_string_memfd</function> and
  61     <function>sd_bus_message_append_string_iovec</function> can be
  62     used to append a single string (item of type <literal>s</literal>)
  63     to message <parameter>m</parameter>.</para>
  64
  65     <para>In case of
  66     <function>sd_bus_message_append_string_memfd</function>, the
  67     contents of <parameter>memfd</parameter> are the string. They must
  68     satisfy the same constraints as described for the
  69     <literal>s</literal> type in
  70     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  71
  72     <para>In case of
  73     <function>sd_bus_message_append_string_iovec</function>, the
  74     payload of <parameter>iov</parameter> is the string. It must
  75     satisfy the same constraints as described for the
  76     <literal>s</literal> type in
  77     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
  78
  79     <para>The <parameter>iov</parameter> argument must point to
  80     <parameter>n</parameter> <structname>struct iovec</structname>
  81     structures. Each structure may have the
  82     <structname>iov_base</structname> field set, in which case the
  83     memory pointed to will be copied into the message, or unset, in
  84     which case a block of spaces (ASCII 32) of length
  85     <structname>iov_len</structname> will be inserted. The
  86     memory pointed at by <parameter>iov</parameter> may be changed
  87     after this call.</para>
  88
  89     <para>The
  90     <function>sd_bus_message_append_string_space</function> function appends
  91     space for a string to message <parameter>m</parameter>. It behaves
  92     similar to <function>sd_bus_message_append_basic</function> with
  93     type <literal>s</literal>, but instead of copying a string into
  94     the message, it returns a pointer to the destination area to
  95     the caller in pointer <parameter>p</parameter>. Space for the string
  96     of length <parameter>size</parameter> plus the terminating
  97     <constant>NUL</constant> is allocated.</para>
  98   </refsect1>
  99
 100   <refsect1>
 101     <title>Return Value</title>
 102
 103     <para>On success, those calls return 0 or a positive integer. On
 104     failure, they returns a negative errno-style error code.</para>
 105   </refsect1>
 106
 107   <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
 108
 109   <xi:include href="libelogind-pkgconfig.xml" />
 110
 111   <refsect1>
 112     <title>See Also</title>
 113
 114     <para>
 115       <!-- 0 /// elogind is in section 8
 116       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 117       --><!-- else -->
 118       <citerefentry><refentrytitle>elogind</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 119       <!-- // 0 -->
 120       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 121       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 122       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
 123     </para>
 124   </refsect1>
 125
 126 </refentry>