-
Notifications
You must be signed in to change notification settings - Fork 0
/
evbuffer_add.3
194 lines (194 loc) · 4.66 KB
/
evbuffer_add.3
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
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
.\" $OpenBSD$
.\" Copyright (c) 2023 Ted Bullock <[email protected]>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate$
.Dt EVBUFFER_ADD 3
.Os
.Sh NAME
.Nm evbuffer_add ,
.Nm evbuffer_add_buffer ,
.Nm evbuffer_add_printf ,
.Nm evbuffer_add_vprintf
.Nd add data to an evbuffer
.Sh SYNOPSIS
.In event.h
.Ft int
.Fn evbuffer_add "struct evbuffer *buf" "const void *data" "size_t datlen"
.Ft int
.Fn evbuffer_add_buffer "struct evbuffer *outbuf" "struct evbuffer *inbuf"
.Ft int
.Fn evbuffer_add_printf "struct evbuffer *buf" "const char *fmt" ...
.In stdarg.h
.Ft int
.Fn evbuffer_add_vprintf "struct evbuffer *buf" "const char *fmt" "va_list ap"
.Sh DESCRIPTION
These functions all append data to an
.Vt evbuffer .
The standard workflow involves adding data to a buffer and later retrieving it
by reading it back in bytes or lines, or by writing it out to a file
descriptor.
Raw bytes are appended to a buffer using the functions
.Fn evbuffer_add ,
.Fn evbuffer_add_buffer
or
.Xr evbuffer_read 3 .
Formatted data is added using the functions
.Fn evbuffer_add_printf
or
.Fn evbuffer_add_vprintf .
.Pp
The event library
.Sy bufferevent
API is an abstraction built on top of the
.Sy evbuffer
API and the core event loop functionality of the library to provide
asynchronous, buffered I/O.
A detailed explanation of
.Sy bufferevents
is available in
.Xr bufferevent_new 3 .
.Pp
If an
.Vt evbuffer
has insufficient space, these functions allocate new memory dynamically using
.Xr evbuffer_expand 3 .
An optional callback function is set using
.Xr evbuffer_setcb 3
to inform programs about changes in buffer size.
These functions must also be invoked with an
.Va evbuffer
structure initialized by
.Xr evbuffer_new 3
otherwise they cause undefined behavior.
.Pp
.Fn evbuffer_add
appends raw bytes from the user-specified pointer
.Fa data
to the
.Va evbuffer
structure
.Fa buf .
The number of bytes to append is denoted by the argument
.Fa datlen .
If
.Fa buf
or
.Fa data
is
.Dv NULL
the function causes undefined behavior, if
.Fa datlen
is zero the function makes no changes to
.Fa buf .
.Pp
.Fn evbuffer_add_buffer
appends all buffered data from the
.Va evbuffer
structure
.Fa inbuf
to the target
.Va evbuffer
structure
.Fa outbuf .
The
.Fa inbuf
buffer is drained in the process, leaving it empty.
The callback notification function is invoked for both
.Va evbuffer
structures.
If either argument is
.Dv NULL ,
the function causes undefined behavior.
.Pp
.Fn evbuffer_add_printf
appends a formatted string
.Fa fmt
to an
.Va evbuffer
structure
.Fa buf .
The semantics of the format string and any subsequent arguments are equivalent
to
.Xr printf 3 .
The function causes undefined behavior if
.Fa buf
is
.Dv NULL .
.Pp
.Fn evbuffer_add_vprintf
also appends a formatted string
.Fa fmt
to an
.Va evbuffer
structure
.Fa buf
and is similar to
.Xr vprintf 3
with argument
.Fa ap
accessed via the variable-length argument facilities of
.Xr va_start 3 .
The function causes undefined behavior if
.Fa buf
is
.Dv NULL .
.Sh RETURN VALUES
These functions return 0 on success or \-1 on failure.
.\" .Sh EXAMPLES
.Sh ERRORS
These functions fail if they attempt to grow the
.Va evbuffer ,
and
.Xr evbuffer_expand 3
is unable to allocate new memory.
Any
.Va errno
value set by the internal call to
.Xr evbuffer_expand 3
is preserved.
.Pp
.Fn evbuffer_add_printf
and
.Fn evbuffer_add_vprintf
use the C library function
.Xr vsnprintf 3
to implement their functionality;
.Va errno
values are preserved if it encounters a problem.
.Sh SEE ALSO
.Xr bufferevent_new 3 ,
.Xr evbuffer_expand 3 ,
.Xr evbuffer_new 3 ,
.Xr evbuffer_setcb 3 ,
.Xr vsnprintf 3
.Sh HISTORY
.Fn evbuffer_add_vprintf
first appeared in libevent-1.2 and has been available since
.Ox 3.9 .
.Pp
The remaining functions first appeared in libevent-0.8 and have been
available since
.Ox 3.6 .
.Sh AUTHORS
.Fn evbuffer_add_vprintf
was written by
.An -nosplit
.An Artur Grabowski .
.Pp
The remaining functions were written by
.An Niels Provos .
.Pp
This manual page was written by
.An Ted Bullock Aq Mt [email protected] .