-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathevbuffer_expand.3
87 lines (87 loc) · 2.39 KB
/
evbuffer_expand.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
.\" $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_EXPAND 3
.Os
.Sh NAME
.Nm evbuffer_expand
.Nd grow allocated buffer size
.Sh SYNOPSIS
.In event.h
.Ft int
.Fn evbuffer_expand "struct evbuffer *buf" "size_t datlen"
.Sh DESCRIPTION
.Fn evbuffer_expand
is used to grow the memory buffer of an
.Vt evbuffer
structure
.Fa buf
by at least
.Fa datlen
bytes of data.
.Pp
If the buffer already has enough space, the function makes no changes.
.Pp
If the buffer does not have enough space, the function resizes it by
allocating a larger block of memory.
The new size of the buffer is calculated to be large enough to hold at least
the sum of the current buffer length and
.Fa datlen .
.Pp
If
.Fa buf
is
.Dv NULL ,
the function causes undefined behavior.
.Sh RETURN VALUES
This function returns 0 when
.Fa buf
has sufficient allocated memory and \-1 if there is an error allocating memory
or if resizing would overflow past
.Dv SIZE_MAX
bytes.
.\" .Sh EXAMPLES
.Sh ERRORS
This function does not set
.Va errno
on all error conditions although if the internal call to
.Xr recallocarray 3
fails,
.Va errno
is preserved.
.Sh SEE ALSO
.Xr evbuffer_new 3
.Sh HISTORY
.Fn evbuffer_expand
first appeared in libevent-0.9 and has been available since
.Ox 3.8 .
.Sh AUTHORS
This function was written by
.An -nosplit
.An Niels Provos .
.Pp
This manual page was written by
.An Ted Bullock Aq Mt [email protected] .
.Sh CAVEATS
The
.Ox
event library version of
.Fn evbuffer_expand
uses
.Xr recallocarray 3
to allocate new memory blocks and guarantee that memory becoming unallocated
is explicitly discarded.
This behavior cannot be relied upon in other versions of the library.