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