-
Notifications
You must be signed in to change notification settings - Fork 0
/
evbuffer_read.3
146 lines (146 loc) · 3.46 KB
/
evbuffer_read.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
.\" $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_READ 3
.Os
.Sh NAME
.Nm evbuffer_read ,
.Nm evbuffer_write
.Nd evbuffer support for file I/O
.Sh SYNOPSIS
.In event.h
.Ft int
.Fn evbuffer_read "struct evbuffer *buf" "int fd" "int howmuch"
.Ft int
.Fn evbuffer_write "struct evbuffer *buf" "int fd"
.Sh DESCRIPTION
The
.Sy evbuffer
API provides functions to provide file I/O to and from
.Va evbuffer
structures.
These functions append to or drain from an
.Va evbuffer
while providing read and write file descriptor operations.
An optional callback function configured with
.Xr evbuffer_setcb 3
is invoked at the successful end of the functions to inform programs about how
the size of the buffer has changed.
.Pp
.Fn evbuffer_read
appends
.Fa howmuch
bytes from the open file descriptor
.Fa fd
to the
.Va evbuffer
structure
.Fa buf .
The function causes undefined behavior if
.Fa buf
is
.Dv NULL .
.Pp
The
.Fa howmuch
argument does not necessarily specify the exact number of bytes to read from
the file descriptor.
It is a
.Em suggested
amount that the function may adjust and is not a guarantee of either a minimum
or maximum.
.Pp
If necessary the function grows the buffer with
.Xr evbuffer_expand 3
to store the calculated number of bytes.
.Pp
.Fn evbuffer_write
attempts to write the entire contents of the
.Vt evbuffer
structure
.Fa buf
to the open file descriptor
.Fa fd .
The buffer is drained in the process, leaving it empty.
The function causes undefined behavior if
.Fa buf
is
.Dv NULL .
.Sh RETURN VALUES
If successful,
.Fn evbuffer_read
returns the number of bytes appended to
.Fa buf .
Upon reading end-of-file, zero is returned.
Upon failure \-1 is returned and
.Va errno
is set to indicate the error.
.Pp
If successful,
.Fn evbuffer_write
returns the number of bytes drained from
.Fa buf
to
.Fa fd .
Upon failure \-1 is returned and
.Va errno
is set to indicate the error.
.\" .Sh EXAMPLES
.Sh ERRORS
.Fn evbuffer_read
fails if
.Xr evbuffer_expand 3
is unable to allocate new memory or the system call
.Xr read 2
reports a problem;
.Va errno
values are preserved.
.Pp
.Fn evbuffer_write
fails if the system call
.Xr write 2
reports a problem;
.Va errno
values are preserved.
.Sh SEE ALSO
.Xr read 2 ,
.Xr write 2 ,
.Xr evbuffer_add 3 ,
.Xr evbuffer_expand 3 ,
.Xr evbuffer_new 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 [email protected] .
.Sh BUGS
.Fn evbuffer_read
and
.Fn evbuffer_write
return an
.Vt int
which can truncate the
.Vt ssize_t
return value of
.Xr read 2
and
.Xr write 2
for very large I/O operations.