-
Notifications
You must be signed in to change notification settings - Fork 0
/
evbuffer_new.3
145 lines (145 loc) · 4.01 KB
/
evbuffer_new.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
.\" $OpenBSD$
.\" Copyright (c) 2023 Ted Bullock <tbullock@comlore.com>
.\"
.\" 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_NEW 3
.Os
.Sh NAME
.Nm evbuffer_new ,
.Nm evbuffer_free ,
.Nm evbuffer_setcb
.Nd evbuffer initialization
.Sh SYNOPSIS
.In event.h
.Ft "struct evbuffer *"
.Fn evbuffer_new void
.Ft void
.Fn evbuffer_free "struct evbuffer *buffer"
.Ft void
.Fo evbuffer_setcb
.Fa "struct evbuffer *buffer"
.Fa "void (*cb)(struct evbuffer *buf, size_t old, size_t new, void * arg)"
.Fa "void *cbarg"
.Fc
.Sh DESCRIPTION
The event library provides a collection of interfaces for managing buffered
input and output in the form of the
.Sy evbuffer
family of functions.
These functions offer fine-grained control over buffering, reading, writing
and processing data.
It is not necessary to use the event loop functionality of the library in
conjunction with
.Sy evbuffer
functions.
.Pp
The
.Va evbuffer
data structure is used throughout the
.Sy evbuffer
API for buffering and manipulating sequences of bytes.
It is a dynamic buffer that can grow as data is added to it and is used
for a variety of purposes, including network and file I/O as well as
intra-process communication.
An optional user-defined callback can be assigned to an
.Va evbuffer
to notify programs of changes to the data structure.
.Pp
.Fn evbuffer_new
allocates memory for a new, empty
.Va evbuffer
structure that is used to store data and is passed to other functions
in the library to append, remove, or modify data in the buffer.
.Pp
.Fn evbuffer_free
releases all resources associated with an
.Va evbuffer
structure.
Memory in the buffer is not zeroed nor is it explicitly discarded.
.Pp
.Fn evbuffer_setcb
configures an
.Vt evbuffer
with an optional user-defined callback
.Va cb .
The event library triggers the callback after the number of bytes stored in
the buffer changes.
In normal program operation, as data is added to and drained from the
.Va evbuffer ,
the callback function provides a mechanism for the program to dynamically
learn about its status.
The arguments are as follows:
.Bl -tag -width 7n
.It Va buffer :
A pointer to an
.Vt evbuffer
structure.
The behavior is undefined if
.Va buffer
is
.Dv NULL .
.It Va cb :
A function pointer to a callback function.
The behavior, if
.Va cb
is
.Dv NULL ,
is to reset the
.Vt evbuffer
to not use a callback.
The function parameters are as follows:
.Pp
.Bl -tag -width Ds -compact
.It Va buf :
A pointer to the
.Vt evbuffer
structure that triggered the callback.
.It Va old :
The original buffer size in bytes before the change that triggered this
callback.
.It Va new :
The new buffer size in bytes after the change that triggered this callback.
.It Va arg :
A void pointer to a user-defined data structure passed to the callback that
corresponds to
.Va cbarg .
.El
.It Va cbarg :
A user-defined data structure that is passed to the callback function
.Va cb
as parameter
.Va arg .
.El
.Sh RETURN VALUES
.Fn evbuffer_new
returns a pointer to a new
.Va evbuffer
structure on success or
.Dv NULL
on failure.
On failure the function sets
.Va errno
equivalent to
.Xr calloc 3 .
.Sh HISTORY
These functions first appeared in libevent-0.8 and have been available since
.Ox 3.6 .
.Sh AUTHORS
The event library and these functions were written by
.An -nosplit
.An Niels Provos .
.Pp
This manual page was written by
.An Ted Bullock Aq Mt tbullock@comlore.com .