-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathevbuffer_remove.3
167 lines (165 loc) · 3.95 KB
/
evbuffer_remove.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
.\" $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_REMOVE 3
.Os
.Sh NAME
.Nm evbuffer_remove ,
.Nm evbuffer_drain
.Nd clear bytes from the beginning of an evbuffer
.Sh SYNOPSIS
.In event.h
.Ft int
.Fn evbuffer_remove "struct evbuffer *buf" "void *data" "size_t datlen"
.Ft void
.Fn evbuffer_drain "struct evbuffer *buf" "size_t len"
.Fd #define EVBUFFER_LENGTH(x) (x)->off
.Fd #define EVBUFFER_DATA(x) (x)->buffer
.Sh DESCRIPTION
These functions provide a mechanism to remove data from the beginning of an
.Vt evbuffer .
An optional callback function is set using
.Xr evbuffer_setcb 3
to inform programs about changes in buffer size.
.Pp
.Fn evbuffer_remove
copies
.Fa datlen
bytes from the
.Vt evbuffer
structure
.Fa buf
to a user-specified pointer
.Fa data
and drains those bytes from the buffer accordingly.
.Pp
If
.Fa datlen
is zero, the function makes no changes to
.Fa buf .
If
.Fa datlen
exceeds the buffer length of
.Fa buf ,
the function copies the available bytes to
.Fa data
and leaves the remaining space uninitialized.
If
.Fa buf
or
.Fa data
is
.Dv NULL ,
or
.Fa data
is not a valid pointer to at least
.Fa datlen
bytes, the function causes undefined behavior.
.Pp
.Fn evbuffer_drain
attempts to remove up to the first
.Fa len
bytes from the
.Vt evbuffer
structure
.Fa buf
by adjusting internal offsets.
If the buffer is shorter than
.Fa len ,
it empties the buffer entirely.
If
.Fa buf
is
.Dv NULL ,
the behavior is undefined.
.Fn evbuffer_drain
does not provide access to removed data nor does it clear removed memory.
.Pp
.Fn EVBUFFER_LENGTH x
expands to the number of bytes stored in
.Vt evbuffer
.Fa x .
.Pp
.Fn EVBUFFER_DATA x
expands to a pointer to the beginning of buffered data in
.Vt evbuffer
.Fa x .
.Pp
These macros cause a segmentation fault if
.Fa x
is
.Dv NULL .
Modifying a buffers length invalidates these expansion results.
.Sh RETURN VALUES
.Fn evbuffer_remove
returns the number of bytes copied to
.Fa data .
.Sh SEE ALSO
.Xr evbuffer_expand 3 ,
.Xr evbuffer_new 3
.Sh HISTORY
.Fn evbuffer_remove
first appeared in libevent-0.9 and has been available since
.Ox 3.8 .
.Pp
.Fn evbuffer_drain ,
.Fn EVBUFFER_LENGTH
and
.Fn EVBUFFER_DATA
first appeared in libevent-0.8 and have been
available since
.Ox 3.6 .
.Sh AUTHORS
These macros and functions were written by
.An -nosplit
.An Niels Provos .
.Pp
This manual page was written by
.An Ted Bullock Aq Mt [email protected] .
.Sh CAVEATS
While the
.Fn EVBUFFER_LENGTH
and
.Fn EVBUFFER_DATA
macros expose the fields of the
.Vt struct evbuffer
data structure, this behavior cannot be relied upon in other versions of the
library as it is subject to change and is not a promise of the
.Sy evbuffer
API.
.Sh BUGS
.Fn evbuffer_remove
returns an
.Vt int
which can truncate the
.Fa size_t datlen
number of bytes removed for large buffers.
.Pp
The following test checks for truncation before invoking the function so the
return value is trusted:
.Bd -literal -offset indent
#include <stdint.h>
/* ... */
size_t datlen;
uint8_t *data;
int bytes_removed;
/* ... */
if (datlen > INT_MAX) {
/* handle the truncation error appropriately */
}
/* advise casting to 'int' to explicitly mark truncation tested */
bytes_removed = (int)evbuffer_remove(buf, data, (int)datlen)
.Ed