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