jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: evbuffer_new.3,v 1.16 2025/06/13 18:34:00 schwarze Exp $
2.\"
3.\" Copyright (c) 2014 David Gwynne <dlg@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: June 13 2025 $
18.Dt EVBUFFER_NEW 3
19.Os
20.Sh NAME
21.Nm evbuffer_new ,
22.Nm evbuffer_free ,
23.Nm evbuffer_setcb ,
24.Nm evbuffer_expand ,
25.Nm evbuffer_add ,
26.Nm evbuffer_add_buffer ,
27.Nm evbuffer_add_printf ,
28.Nm evbuffer_add_vprintf ,
29.Nm evbuffer_drain ,
30.Nm evbuffer_remove ,
31.Nm evbuffer_write ,
32.Nm evbuffer_read ,
33.Nm evbuffer_find ,
34.Nm evbuffer_readline ,
35.Nm evbuffer_readln ,
36.Nm EVBUFFER_LENGTH ,
37.Nm EVBUFFER_DATA
38.Nd libevent utility API for buffered input/output
39.Sh SYNOPSIS
40.Lb libevent
41.In event.h
42.Ft struct evbuffer *
43.Fn "evbuffer_new" "void"
44.Ft void
45.Fn "evbuffer_free" "struct evbuffer *buf"
46.Ft void
47.Fo evbuffer_setcb
48.Fa "struct evbuffer *buf"
49.Fa "void (*cb)(struct evbuffer *, size_t, size_t, void *)"
50.Fa "void *cbarg"
51.Fc
52.Ft int
53.Fn "evbuffer_expand" "struct evbuffer *buf" "size_t datlen"
54.Ft int
55.Fn "evbuffer_add" "struct evbuffer *buf" "const void *data" "size_t size"
56.Ft int
57.Fn "evbuffer_add_buffer" "struct evbuffer *dst" "struct evbuffer *src"
58.Ft int
59.Fn "evbuffer_add_printf" "struct evbuffer *buf" "const char *fmt" "..."
60.Ft int
61.Fn "evbuffer_add_vprintf" "struct evbuffer *buf" "const char *fmt" "va_list ap"
62.Ft void
63.Fn "evbuffer_drain" "struct evbuffer *buf" "size_t size"
64.Ft int
65.Fn "evbuffer_remove" "struct evbuffer *buf" "void *data" "size_t datlen"
66.Ft int
67.Fn "evbuffer_write" "struct evbuffer *buf" "int fd"
68.Ft int
69.Fn "evbuffer_read" "struct evbuffer *buf" "int fd" "int size"
70.Ft u_char *
71.Fn "evbuffer_find" "struct evbuffer *buf" "const u_char *data" "size_t size"
72.Ft char *
73.Fn "evbuffer_readline" "struct evbuffer *buf"
74.Ft char *
75.Fo evbuffer_readln
76.Fa "struct evbuffer *buf"
77.Fa "size_t *read_out"
78.Fa "enum evbuffer_eol_style eol_style"
79.Fc
80.Ft size_t
81.Fn "EVBUFFER_LENGTH" "const struct evbuffer *buf"
82.Ft u_char *
83.Fn "EVBUFFER_DATA" "const struct evbuffer *buf"
84.Sh DESCRIPTION
85The evbuffer API provides an implementation of buffering for use with
86libevent.
87.Pp
88.Fn evbuffer_new
89allocates and initialises a new evbuffer structure.
90.Pp
91.Fn evbuffer_free
92deallocates the evbuffer structure
93.Fa buf
94and any referenced storage.
95.Pp
96.Fn evbuffer_setcb
97sets the callback
98.Fa cb
99to be invoked with argument
100.Fa cbarg
101when the data in evbuffer
102.Fa buf
103is modified.
104.Pp
105.Fn evbuffer_expand
106expands the available space in
107.Fa buf
108to at least
109.Fa datlen
110bytes.
111.Pp
112.Fn evbuffer_add
113appends a copy of
114.Fa size
115bytes from buffer
116.Fa data
117to the end of the evbuffer
118.Fa buf .
119.Pp
120.Fn evbuffer_add_buffer
121moves the data off the
122.Fa src
123evbuffer and appends it to
124.Fa dst .
125.Pp
126.Fn evbuffer_add_printf
127appends a
128.Xr printf 3
129style formatted string specified by
130.Fa fmt
131to the end of
132.Fa buf .
133.Pp
134.Fn evbuffer_add_vprintf
135appends a
136.Xr vprintf 3
137style formatted string specified by
138.Fa fmt
139with a va_list
140.Fa ap
141to the end of
142.Fa buf .
143.Pp
144.Fn evbuffer_drain
145deletes
146.Fa size
147bytes from the beginning of the evbuffer
148.Fa buf .
149.Pp
150.Fn evbuffer_remove
151reads and drains up to
152.Fa datlen
153bytes from the beginning of the evbuffer
154.Fa buf
155into
156.Fa data .
157.Pp
158.Fn evbuffer_write
159writes and drains the contents of evbuffer
160.Fa buf
161to the file descriptor
162.Fa fd .
163.Pp
164.Fn evbuffer_read
165appends up to
166.Fa size
167bytes on to the end of the evbuffer
168.Fa buf
169by reading from the file descriptor
170.Fa fd .
171.Pp
172.Fn evbuffer_find
173finds the
174.Fa size
175length string
176.Fa data
177in the evbuffer
178.Fa buf .
179.Pp
180.Fn evbuffer_readline
181reads and drains a single line from the evbuffer
182.Fa buf .
183A line is delimited by "\en", "\er", "\er\en", or "\en\er".
184It is the responsibility of the caller to free the returned line with
185.Xr free 3 .
186.Pp
187.Fn evbuffer_readln
188reads and drains a single line from the evbuffer
189.Fa buf .
190The length of the line will be stored in
191.Fa read_out
192on success.
193It is the responsibility of the caller to free the returned line with
194.Xr free 3 .
195The line delimiter is specified as one of the following:
196.Bl -tag -width xxx -offset indent
197.It Dv EVBUFFER_EOL_ANY
198Any sequence of newline or carriage return characters.
199.It Dv EVBUFFER_EOL_CRLF
200A new line optionally preceded by a carriage return.
201.It Dv EVBUFFER_EOL_CRLF_STRICT
202A carriage return followed by a new line character.
203.It Dv EVBUFFER_EOL_LF
204A new line character.
205.El
206.Pp
207.Fn EVBUFFER_LENGTH
208reports how many bytes are stored in the evbuffer
209.Fa buf .
210.Sh RETURN VALUES
211.Fn evbuffer_new
212returns a pointer to a newly allocated buffer on success,
213or
214.Dv NULL
215on failure and sets
216.Va errno
217to indicate the failure.
218.Pp
219.Fn evbuffer_expand ,
220.Fn evbuffer_add ,
221and
222.Fn evbuffer_add_buffer
223return 0 on success,
224or -1 on failure and set
225.Va errno
226to indicate the failure.
227.Pp
228.Fn evbuffer_add_printf
229and
230.Fn evbuffer_add_vprintf
231return the number of bytes added on success,
232or -1 on failure.
233.Pp
234.Fn evbuffer_remove
235returns the number of bytes read.
236.Pp
237.Fn evbuffer_write
238returns the number of bytes written and drained on success,
239or -1 on failure and sets
240.Va errno
241to indicate the failure.
242.Pp
243.Fn evbuffer_read
244returns the number of bytes appended to the evbuffer on success,
2450 on an end of file condition,
246or -1 on failure and sets
247.Va errno
248to indicate the failure.
249.Pp
250.Fn evbuffer_find
251returns a pointer to the start of the string within the evbuffer on success,
252or
253.Dv NULL
254on failure.
255.Pp
256.Fn evbuffer_readline
257and
258.Fn evbuffer_readln
259return a pointer to the line on success,
260or
261.Dv NULL
262on failure.
263.Pp
264.Fn EVBUFFER_LENGTH
265returns the number of bytes available in the evbuffer.
266.Pp
267.Fn EVBUFFER_DATA
268returns a pointer to the evbuffer
269.Fa buf
270on success.
271.Sh SEE ALSO
272.Xr errno 2 ,
273.Xr event 3 ,
274.Xr free 3 ,
275.Xr printf 3
276.Sh AUTHORS
277The
278.Nm event
279library was written by
280.An Niels Provos .