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