forked from libevent/libevent-book
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Ref5_evutil.txt
343 lines (265 loc) · 10.3 KB
/
Ref5_evutil.txt
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
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
include::license.txt[]
:language: C
// FIXME: This part incorporates way too many standards by reference.
Helper functions and types for Libevent
---------------------------------------
The <event2/util.h> header defines many functions that you might find
helpful for implementing portable applications using Libevent.
Libevent uses these types and functions internally.
Basic types
~~~~~~~~~~~
evutil_socket_t
^^^^^^^^^^^^^^^
Most everywhere except Windows, a socket is an int, and the operating
system hands them out in numeric order. Using the Windows socket API,
however, a socket is of type SOCKET, which is really a pointer-like OS
handle, and the order you receive them is undefined. We define the
evutil_socket_t type to be an integer that can hold the output of
socket() or accept() without risking pointer truncation on Windows.
.Definition
[code]
--------
#ifdef WIN32
#define evutil_socket_t intptr_t
#else
#define evutil_socket_t int
#endif
--------
This type was introduced in Libevent 2.0.1-alpha.
Standard integer types
^^^^^^^^^^^^^^^^^^^^^^
Often you will find yourself on a C system that missed out on the 21st
century and therefore does not implement the standard C99
stdint.h header. For this situation, Libevent defines its own
versions of the bit-width-specific integers from stdint.h:
[options="header",width="40%"]
|==============================
| Type |Width |Signed
|ev_uint64_t |64 |No
|ev_int64_t |64 |Yes
|ev_uint32_t |32 |No
|ev_int32_t |32 |Yes
|ev_uint16_t |16 |No
|ev_int16_t |16 |Yes
|ev_uint8_t |8 |No
|ev_int8_t |8 |Yes
|=============================
As in the C99 standard, each type has exactly the specified width, in
bits.
These types were introduced in Libevent 1.4.0-beta.
Miscellaneous compatibility types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ev_ssize_t type is defined to ssize_t (signed size_t) on platforms that
have one, and to a reasonable default on platforms that don't.
Some implementations of the sockets API provide a length type, socklen_t, and
some do not. The ev_socklen_t is defined to this type where it exists, and a
reasonable default otherwise.
The ev_ssize_t type was added in Libevent 2.0.2-alpha. The ev_socklen_t type
was new in Libevent 2.0.3-alpha.
Timer portability functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Not every platform defines the standard timeval manipulation functions.
.Interface
[code]
--------
#define evutil_timeradd(tvp, uvp, vvp) /* ... */
#define evutil_timersub(tvp, uvp, vvp) /* ... */
--------
These macros add or subtract (respectively) their first two arguments,
and stores the result in the third.
.Interface
[code]
--------
#define evutil_timerclear(tvp) /* ... */
#define evutil_timerisset(tvp) /* ... */
--------
Clearing a timeval sets its value to zero. Checking whether it is set
compares its value against zero.
.Interface
[code]
--------
#define evutil_timercmp(tvp, uvp, cmp)
--------
The evutil_timercmp macro compares two timevals, and yields true if
they are in the relationship specified by the relational operator
'cmp'. For example, 'evutil_timercmp(t1, t2, <=)' means, "Is t1 <=
t2?" Note that unlike some operating systems' versions, Libevent's timercmp
supports all the C relational operations (that is, <, >, ==, !=, <=, and >=).
.Interface
[code]
--------
int evutil_gettimeofday(struct timeval *tv, struct timezone *tz);
--------
The evutil_gettimeofday function sets 'tv' to the current time. The
tz argument is unused.
.Example
[code]
--------
struct timeval tv1, tv2, tv3;
/* Set tv1 = 5.5 seconds */
tv1.tv_sec = 5; tv1.tv_usec = 500*1000;
/* Set tv2 = now */
evutil_gettimeofday(&tv2, NULL);
/* Set tv3 = 5.5 seconds in the future */
evutil_timeradd(&tv1, &tv2, &tv3);
/* all 3 should print true */
if (evutil_timercmp(&tv1, &tv1, ==)) /* == "If tv1 == tv1" */
puts("5.5 sec == 5.5 sec");
if (evutil_timercmp(&tv3, &tv2, >=)) /* == "If tv3 >= tv2" */
puts("The future is after the present.");
if (evutil_timercmp(&tv1, &tv2, <)) /* == "If tv1 < tv2" */
puts("It is no longer the past.");
--------
These functions were introduced in Libevent 1.4.0-beta, except for
evutil_gettimeofday(), which was introduced in Libevent 2.0.
NOTE: It wasn't safe to use <= or >= with timercmp before Libevent
1.4.4 beta.
Socket API compatibility
~~~~~~~~~~~~~~~~~~~~~~~~
This section exists because, for historical reasons, Windows has never
really implemented the Berkeley sockets API in a nice compatible (and
nicely compatible) way. Here are some functions you can use in order
to pretend that it has.
.Interface
[code]
--------
#define EVUTIL_CLOSESOCKET(s) /* ... */
--------
This macro closes a socket. On Unix, it's an alias for close(); on
Windows, it calls closesocket(). (You can't use close() on sockets
on Windows, and nobody else defines a closesocket().)
.Interface
[code]
--------
#define EVUTIL_SOCKET_ERROR()
#define EVUTIL_SET_SOCKET_ERROR(errcode)
#define evutil_socket_geterror(sock)
#define evutil_socket_error_to_string(errcode)
--------
These macros access and manipulate socket error codes.
EVUTIL_SOCKET_ERROR() returns the global error code for the last
socket operation from this thread, and evutil_socket_geterror() does
so for a particular socket. (Both are errno on Unix-like systems.)
EVUTIL_SET_SOCKET_ERROR() changes the current socket error code (like
setting errno on Unix), and evutil_socket_error_to_string() returns a
string representation of a given socket error code (like strerror() on
Unix).
(We need these functions because Windows doesn't use errno
for errors from socket functions, but instead uses WSAGetLastError().)
Note that the Windows socket errors are not the same as the standard-C
errors you would see in errno; watch out.
.Interface
[code]
--------
int evutil_make_socket_nonblocking(evutil_socket_t sock);
--------
Even the call you need to do nonblocking IO on a socket is not
portable to Windows. This function takes a new socket (from socket()
or accept()) and turns it into a nonblocking socket. (It sets O_NONBLOCK
on Unix and FIONBIO on Windows.)
.Interface
[code]
--------
int evutil_make_listen_socket_reuseable(evutil_socket_t sock);
--------
This function makes sure that the address used by a listener socket
will be available to another socket immediately after the socket is
closed. (It sets SO_REUSEADDR on Unix and does nothing on Windows.
You don't want to use SO_REUSEADDR on Windows; it means something
different there.)
.Interface
[code]
--------
int evutil_socketpair(int family, int type, int protocol,
evutil_socket_t sv[2]);
--------
This function behaves as the Unix socketpair() call: it makes two
sockets that are connected with each other and can be used with
ordinary socket IO calls. It stores the two sockets in sv[0] and
sv[1], and returns 0 for success and -1 for failure.
On Windows, this only supports family AF_INET, type SOCK_STREAM, and
protocol 0. Note that this can fail on some Windows hosts where
firewall software has cleverly firewalled 127.0.0.1 to keep the host
from talking to itself.
These functions were introduced in Libevent 1.4.0-beta.
Portable string manipulation functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
ev_int64_t evutil_strtoll(const char *s, char **endptr, int base);
--------
This function behaves as strtol, but handles 64-bit integers. On some
platforms, it only supports Base 10.
.Interface
[code]
--------
int evutil_snprintf(char *buf, size_t buflen, const char *format, ...);
int evutil_vsnprintf(char *buf, size_t buflen, const char *format, va_list ap);
--------
These snprintf-replacement functions behave as the standard snprintf
and vsnprintf interfaces. They return the number of bytes that would
have been written into the buffer had it been long enough, not
counting the terminating NUL byte. (This behavior conforms to the C99
snprintf() standard, and is in contrast to the Windows _snprintf(),
which returns a negative number if the string would not fit in the buffer.)
// XXXX Is this accurate?
The evutil_strtoll() function has been in Libevent since 1.4.2-rc.
These other functions first appeared in 2.0.1-alpha.
Locale-independent string manipulation functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes, when implementing ASCII-based protocols, you want to manipulate
strings according to ASCII's notion of character type, regardless of your
current locale. Libevent provides a few functions to help with this:
.Interface
[code]
--------
int evutil_ascii_strcasecmp(const char *str1, const char *str2);
int evutil_ascii_strncasecmp(const char *str1, const char *str2, size_t n);
--------
These functions behave as strcasecmp() and strncasecmp(), except that they
always compare using the ASCII character set, regardless of the current
locale. They were first exposed in Libevent 2.0.3-alpha.
// XXX explain why you would use these.
IPv6 helper and portability functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
const char *evutil_inet_ntop(int af, const void *src, char *dst, size_t len);
int evutil_inet_pton(int af, const char *src, void *dst);
--------
These functions behave as the standard inet_ntop() and inet_pton()
functions for parsing and formatting IPv4 and IPv6 addresses.
// XXX say more!
.Interface
[code]
--------
int evutil_parse_sockaddr_port(const char *str, struct sockaddr *out,
int *outlen);
--------
This function parses an address from 'str' and writes the result to
'out'. The 'outlen' argument must point to an integer holding the
number of bytes available in 'out'; it is altered to hold the number
of bytes actually used. This function returns 0 on success and -1 on
failure. It recognizes the following address formats:
- [ipv6]:port (as in "[ffff::]:80")
- ipv6 (as in "ffff::")
- [ipv6] (as in "[ffff::]")
- ipv4:port (as in "1.2.3.4:80")
- ipv4 (as in "1.2.3.4")
If no port is given, the port in the resulting sockaddr is set to 0.
// XXX when did these appear?
Structure macro portability functions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.Interface
[code]
--------
#define evutil_offsetof(type, field) /* ... */
--------
As the standard offsetof macro, this macro yields the number of bytes from
the start of 'type' at which 'field' occurs.
This function was introduced in Libevent 2.0.1-alpha. It was buggy in every
version before Libevent 2.0.3-alpha.
// FIXME Undocumented: EVUTIL_CHECK_FMT, evutil_sockaddr_cmp,
// evutil_{getaddrinfo,freeadrinfo,gai_strerror}.