1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
<refentry id="refbufapp">
<refmeta>
<refentrytitle>ne_buffer_append</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname id="ne_buffer_append">ne_buffer_append</refname>
<refname id="ne_buffer_zappend">ne_buffer_zappend</refname>
<refname id="ne_buffer_qappend">ne_buffer_qappend</refname>
<refname id="ne_buffer_concat">ne_buffer_concat</refname>
<refname id="ne_buffer_snprintf">ne_buffer_snprintf</refname>
<refpurpose>append data to a string buffer</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include <ne_string.h></funcsynopsisinfo>
<funcprototype>
<funcdef>void <function>ne_buffer_append</function></funcdef>
<paramdef>ne_buffer *<parameter>buf</parameter></paramdef>
<paramdef>const char *<parameter>string</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ne_buffer_zappend</function></funcdef>
<paramdef>ne_buffer *<parameter>buf</parameter></paramdef>
<paramdef>const char *<parameter>string</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ne_buffer_qappend</function></funcdef>
<paramdef>ne_buffer *<parameter>buf</parameter></paramdef>
<paramdef>const char *<parameter>string</parameter></paramdef>
<paramdef>size_t <parameter>len</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>ne_buffer_concat</function></funcdef>
<paramdef>ne_buffer *<parameter>buf</parameter></paramdef>
<paramdef>...</paramdef>
</funcprototype>
<funcprototype>
<funcdef>size_t <function>ne_buffer_snprintf</function></funcdef>
<paramdef>ne_buffer *<parameter>buf</parameter></paramdef>
<paramdef>size_t <parameter>max</parameter></paramdef>
<paramdef>const char *<parameter>format</parameter></paramdef>
<paramdef>...</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>The <function>ne_buffer_append</function> and
<function>ne_buffer_zappend</function> functions append a string to
the end of a buffer; extending the buffer as necessary. The
<parameter>len</parameter> passed to
<function>ne_buffer_append</function> specifies the length of the
string to append; there must be no &nul; terminator in the first
<parameter>len</parameter> bytes of the string.
<function>ne_buffer_zappend</function> must be passed a
&nul;-terminated string.</para>
<para>The <function>ne_buffer_qappend</function> function
behaves similarly to <function>ne_buffer_append</function>,
except that any non-ASCII characters or ASCII control
characters are escaped using C-style hex escaping. For
example, the C string <literal>"foo<TAB>bar"</literal>,
where TAB represents ASCII character 9, would be appended as
<literal>"foo\x09bar"</literal>. Any &nul; bytes within the
length specified are also escaped. This function is useful to
make strings from untrusted sources safe for logging or output
in a user interface.</para>
<para>The <function>ne_buffer_concat</function> function takes
a variable-length argument list; each argument must be a
<type>char *</type> pointer to a &nul;-terminated string. A
&null; pointer must be given as the last argument to mark the
end of the list. The strings are appended to the buffer in
the order given. None of the strings passed to
<function>ne_buffer_concat</function> are modified.</para>
<para>The <function>ne_buffer_snprintf</function> function behaves
like <function>snprintf</function>, appending the output string
formatted according to the <parameter>format</parameter> parameter.
At most <parameter>max</parameter> bytes are written including the
trailing &nul; terminator.</para>
</refsect1>
<refsect1>
<title>Return value</title>
<para>The <function>ne_buffer_snprintf</function> function
returns the number of bytes appended
<emphasis>excluding</emphasis> the trailing &nul;
terminator.</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>The following code will output "<literal>Hello, world.
And goodbye.</literal>".</para>
<programlisting>ne_buffer *buf = ne_buffer_create();
ne_buffer_zappend(buf, "Hello");
ne_buffer_concat(buf, ", world. ", "And ", NULL);
ne_buffer_snprintf(buf, 10, "%s.", "goodbye");
puts(buf->data);
ne_buffer_destroy(buf);</programlisting>
</refsect1>
<refsect1>
<title>See also</title>
<para><xref linkend="ne_buffer"/>, <xref linkend="ne_buffer_create"/>,
<xref linkend="ne_buffer_destroy"/></para>
</refsect1>
</refentry>
|
