chiark / gitweb /
analyze: change behaviour of combined --to/from--pattern
[elogind.git] / 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 This file is part of systemd.
7
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
9
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
14
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="sd_bus_message_append_string_memfd" conditional="ENABLE_KDBUS"
25           xmlns:xi="http://www.w3.org/2001/XInclude">
26
27   <refentryinfo>
28     <title>sd_bus_message_append_string_memfd</title>
29     <productname>systemd</productname>
30
31     <authorgroup>
32       <author>
33         <contrib>A monkey with a typewriter</contrib>
34         <firstname>Zbigniew</firstname>
35         <surname>Jędrzejewski-Szmek</surname>
36         <email>zbyszek@in.waw.pl</email>
37       </author>
38     </authorgroup>
39   </refentryinfo>
40
41   <refmeta>
42     <refentrytitle>sd_bus_message_append_string_memfd</refentrytitle>
43     <manvolnum>3</manvolnum>
44   </refmeta>
45
46   <refnamediv>
47     <refname>sd_bus_message_append_string_memfd</refname>
48     <refname>sd_bus_message_append_string_iovec</refname>
49     <refname>sd_bus_message_append_string_space</refname>
50
51     <refpurpose>Attach a string to a message</refpurpose>
52   </refnamediv>
53
54   <refsynopsisdiv>
55     <funcsynopsis>
56       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
57
58       <funcprototype>
59         <funcdef>int sd_bus_message_append_string_memfd</funcdef>
60         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
61         <paramdef>int <parameter>memfd</parameter></paramdef>
62       </funcprototype>
63
64       <funcprototype>
65         <funcdef>int sd_bus_message_append_string_iovec</funcdef>
66         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
67         <paramdef>const struct iovec *<parameter>iov</parameter></paramdef>
68         <paramdef>unsigned <parameter>n</parameter></paramdef>
69       </funcprototype>
70
71       <funcprototype>
72         <funcdef>int sd_bus_message_append_string_space</funcdef>
73         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
74         <paramdef>size_t <parameter>size</parameter></paramdef>
75         <paramdef>char **<parameter>s</parameter></paramdef>
76       </funcprototype>
77     </funcsynopsis>
78   </refsynopsisdiv>
79
80   <refsect1>
81     <title>Description</title>
82
83     <para>The functions
84     <function>sd_bus_message_append_string_memfd</function> and
85     <function>sd_bus_message_append_string_iovec</function> can be
86     used to append a single string (item of type <literal>s</literal>)
87     to message <parameter>m</parameter>.</para>
88
89     <para>In case of
90     <function>sd_bus_message_append_string_memfd</function>, the
91     contents of <parameter>memfd</parameter> are the string. They must
92     satisfy the same constraints as described for the
93     <literal>s</literal> type in
94     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
95
96     <para>In case of
97     <function>sd_bus_message_append_string_iovec</function>, the
98     payload of <parameter>iov</parameter> is the string. It must
99     satisfy the same constraints as described for the
100     <literal>s</literal> type in
101     <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
102
103     <para>The <parameter>iov</parameter> argument must point to
104     <parameter>n</parameter> <structname>struct iovec</structname>
105     structures. Each structure may have the
106     <structname>iov_base</structname> field set, in which case the
107     memory pointed to will be copied into the message, or unset, in
108     which case a block of spaces (ASCII 32) of length
109     <structname>iov_len</structname> will be inserted. The
110     memory pointed at by <parameter>iov</parameter> may be changed
111     after this call.</para>
112
113     <para>The
114     <function>sd_bus_message_append_string_space</function> function appends
115     space for a string to message <parameter>m</parameter>. It behaves
116     similar to <function>sd_bus_message_append_basic</function> with
117     type <literal>s</literal>, but instead of copying a string into
118     the message, it returns a pointer to the destination area to
119     the caller in pointer <parameter>p</parameter>. Space for the string
120     of length <parameter>size</parameter> plus the terminating
121     <constant>NUL</constant> is allocated.</para>
122   </refsect1>
123
124   <refsect1>
125     <title>Return Value</title>
126
127     <para>On success, those calls return 0 or a positive integer. On
128     failure, they returns a negative errno-style error code.</para>
129   </refsect1>
130
131   <xi:include href="sd_bus_message_append_basic.xml" xpointer="errors" />
132
133   <refsect1>
134     <title>Notes</title>
135
136     <para>The functions described here are available as a shared library,
137     which can be compiled and linked to with the
138     <constant>libsystemd</constant> <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
139     file.</para>
140   </refsect1>
141
142   <refsect1>
143     <title>See Also</title>
144
145     <para>
146       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
147       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
148       <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
149       <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html">The D-Bus specification</ulink>
150     </para>
151   </refsect1>
152
153 </refentry>