| blob | 34b26cd8f45422023333eb0826ca972d45eb84c1 |
1 .TH "event2/util.h" 3 "Tue Jan 27 2015" "libevent" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 event2/util.h \-
6 .PP
7 Common convenience functions for cross-platform portability and related socket manipulations\&.
9 .SH SYNOPSIS
10 .br
11 .PP
12 \fC#include <event2/event-config\&.h>\fP
13 .br
14 \fC#include <stdarg\&.h>\fP
15 .br
16 \fC#include <sys/socket\&.h>\fP
17 .br
19 .SS "Data Structures"
21 .in +1c
22 .ti -1c
23 .RI "struct \fBevutil_addrinfo\fP"
24 .br
25 .RI "\fIA definition of struct addrinfo for systems that lack it\&. \fP"
26 .in -1c
27 .SS "Macros"
29 .in +1c
30 .ti -1c
31 .RI "#define \fBev_socklen_t\fP socklen_t"
32 .br
33 .ti -1c
34 .RI "#define \fBEVUTIL_CLOSESOCKET\fP(s) \fBevutil_closesocket\fP(s)"
35 .br
36 .ti -1c
37 .RI "#define \fBevutil_offsetof\fP(type, field) ((off_t)(&((type *)0)->field))"
38 .br
39 .RI "\fIReplacement for offsetof on platforms that don't define it\&. \fP"
40 .ti -1c
41 .RI "#define \fBevutil_socket_t\fP int"
42 .br
43 .RI "\fIA type wide enough to hold the output of 'socket()' or 'accept()'\&. \fP"
44 .ti -1c
45 .RI "#define \fBevutil_timercmp\fP(tvp, uvp, cmp)"
46 .br
47 .RI "\fIReturn true iff the tvp is related to uvp according to the relational operator cmp\&. \fP"
48 .ti -1c
49 .RI "#define \fBevutil_timerisset\fP(tvp) ((tvp)->tv_sec || (tvp)->tv_usec)"
50 .br
51 .in -1c
52 .PP
53 .RI "\fBStandard integer types\&.\fP"
54 .br
55 Integer type definitions for types that are supposed to be defined in the C99-specified stdint\&.h\&.
56 .PP
57 Shamefully, some platforms do not include stdint\&.h, so we need to replace it\&. (If you are on a platform like this, your C headers are now over 10 years out of date\&. You should bug them to do something about this\&.)
58 .PP
59 We define:
60 .PP
61 .IP "\fBev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t \fP" 1c
62 unsigned integer types of exactly 64, 32, 16, and 8 bits respectively\&.
63 .IP "\fBev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t \fP" 1c
64 signed integer types of exactly 64, 32, 16, and 8 bits respectively\&.
65 .IP "\fBev_uintptr_t, ev_intptr_t \fP" 1c
66 unsigned/signed integers large enough to hold a pointer without loss of bits\&.
67 .IP "\fBev_ssize_t \fP" 1c
68 A signed type of the same size as size_t
69 .IP "\fBev_off_t \fP" 1c
70 A signed type typically used to represent offsets within a (potentially large) file
71 .PP
73 .PP
74 .in +1c
75 .in +1c
76 .ti -1c
77 .RI "#define \fBev_uint64_t\fP \&.\&.\&."
78 .br
79 .ti -1c
80 .RI "#define \fBev_int64_t\fP \&.\&.\&."
81 .br
82 .ti -1c
83 .RI "#define \fBev_uint32_t\fP \&.\&.\&."
84 .br
85 .ti -1c
86 .RI "#define \fBev_int32_t\fP \&.\&.\&."
87 .br
88 .ti -1c
89 .RI "#define \fBev_uint16_t\fP \&.\&.\&."
90 .br
91 .ti -1c
92 .RI "#define \fBev_int16_t\fP \&.\&.\&."
93 .br
94 .ti -1c
95 .RI "#define \fBev_uint8_t\fP \&.\&.\&."
96 .br
97 .ti -1c
98 .RI "#define \fBev_int8_t\fP \&.\&.\&."
99 .br
100 .ti -1c
101 .RI "#define \fBev_uintptr_t\fP ev_uint32_t"
102 .br
103 .ti -1c
104 .RI "#define \fBev_intptr_t\fP ev_int32_t"
105 .br
106 .ti -1c
107 .RI "#define \fBev_ssize_t\fP ssize_t"
108 .br
109 .ti -1c
110 .RI "#define \fBev_off_t\fP off_t"
111 .br
112 .in -1c
113 .in -1c
114 .PP
115 .RI "\fBLimits for integer types\fP"
116 .br
117 These macros hold the largest or smallest values possible for the ev_[u]int*_t types\&.
118 .PP
119 .in +1c
120 .in +1c
121 .ti -1c
122 .RI "#define \fBEV_UINT64_MAX\fP ((((ev_uint64_t)0xffffffffUL) << 32) | 0xffffffffUL)"
123 .br
124 .ti -1c
125 .RI "#define \fBEV_INT64_MAX\fP ((((ev_int64_t) 0x7fffffffL) << 32) | 0xffffffffL)"
126 .br
127 .ti -1c
128 .RI "#define \fBEV_INT64_MIN\fP ((-EV_INT64_MAX) - 1)"
129 .br
130 .ti -1c
131 .RI "#define \fBEV_UINT32_MAX\fP ((ev_uint32_t)0xffffffffUL)"
132 .br
133 .ti -1c
134 .RI "#define \fBEV_INT32_MAX\fP ((ev_int32_t) 0x7fffffffL)"
135 .br
136 .ti -1c
137 .RI "#define \fBEV_INT32_MIN\fP ((-EV_INT32_MAX) - 1)"
138 .br
139 .ti -1c
140 .RI "#define \fBEV_UINT16_MAX\fP ((ev_uint16_t)0xffffUL)"
141 .br
142 .ti -1c
143 .RI "#define \fBEV_INT16_MAX\fP ((ev_int16_t) 0x7fffL)"
144 .br
145 .ti -1c
146 .RI "#define \fBEV_INT16_MIN\fP ((-EV_INT16_MAX) - 1)"
147 .br
148 .ti -1c
149 .RI "#define \fBEV_UINT8_MAX\fP 255"
150 .br
151 .ti -1c
152 .RI "#define \fBEV_INT8_MAX\fP 127"
153 .br
154 .ti -1c
155 .RI "#define \fBEV_INT8_MIN\fP ((-EV_INT8_MAX) - 1)"
156 .br
157 .in -1c
158 .in -1c
159 .PP
160 .RI "\fBLimits for SIZE_T and SSIZE_T\fP"
161 .br
163 .in +1c
164 .in +1c
165 .ti -1c
166 .RI "#define \fBEV_SIZE_MAX\fP \&.\&.\&."
167 .br
168 .ti -1c
169 .RI "#define \fBEV_SSIZE_MAX\fP \&.\&.\&."
170 .br
171 .ti -1c
172 .RI "#define \fBEV_SSIZE_MIN\fP ((-EV_SSIZE_MAX) - 1)"
173 .br
174 .in -1c
175 .in -1c
176 .PP
177 .RI "\fBSocket error functions\fP"
178 .br
179 These functions are needed for making programs compatible between Windows and Unix-like platforms\&.
180 .PP
181 You see, Winsock handles socket errors differently from the rest of the world\&. Elsewhere, a socket error is like any other error and is stored in errno\&. But winsock functions require you to retrieve the error with a special function, and don't let you use strerror for the error codes\&. And handling EWOULDBLOCK is \&.\&.\&. different\&.
182 .PP
183 .in +1c
184 .in +1c
185 .ti -1c
186 .RI "#define \fBEVUTIL_SOCKET_ERROR\fP() \&.\&.\&."
187 .br
188 .RI "\fIReturn the most recent socket error\&. \fP"
189 .ti -1c
190 .RI "#define \fBEVUTIL_SET_SOCKET_ERROR\fP(errcode) \&.\&.\&."
191 .br
192 .RI "\fIReplace the most recent socket error with errcode\&. \fP"
193 .ti -1c
194 .RI "#define \fBevutil_socket_geterror\fP(sock) \&.\&.\&."
195 .br
196 .RI "\fIReturn the most recent socket error to occur on sock\&. \fP"
197 .ti -1c
198 .RI "#define \fBevutil_socket_error_to_string\fP(errcode) \&.\&.\&."
199 .br
200 .RI "\fIConvert a socket error to a string\&. \fP"
201 .in -1c
202 .in -1c
203 .PP
204 .RI "\fBManipulation macros for struct timeval\&.\fP"
205 .br
206 We define replacements for timeradd, timersub, timerclear, timercmp, and timerisset\&.
207 .PP
208 .in +1c
209 .in +1c
210 .ti -1c
211 .RI "#define \fBevutil_timeradd\fP(tvp, uvp, vvp)"
212 .br
213 .ti -1c
214 .RI "#define \fBevutil_timersub\fP(tvp, uvp, vvp)"
215 .br
216 .ti -1c
217 .RI "#define \fBevutil_timerclear\fP(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0"
218 .br
219 .in -1c
220 .in -1c
221 .PP
222 .RI "\fBevutil_getaddrinfo() error codes\fP"
223 .br
224 These values are possible error codes for \fBevutil_getaddrinfo()\fP and related functions\&.
225 .PP
226 .in +1c
227 .in +1c
228 .ti -1c
229 .RI "#define \fBEVUTIL_EAI_ADDRFAMILY\fP -901"
230 .br
231 .ti -1c
232 .RI "#define \fBEVUTIL_EAI_AGAIN\fP -902"
233 .br
234 .ti -1c
235 .RI "#define \fBEVUTIL_EAI_BADFLAGS\fP -903"
236 .br
237 .ti -1c
238 .RI "#define \fBEVUTIL_EAI_FAIL\fP -904"
239 .br
240 .ti -1c
241 .RI "#define \fBEVUTIL_EAI_FAMILY\fP -905"
242 .br
243 .ti -1c
244 .RI "#define \fBEVUTIL_EAI_MEMORY\fP -906"
245 .br
246 .ti -1c
247 .RI "#define \fBEVUTIL_EAI_NODATA\fP -907"
248 .br
249 .ti -1c
250 .RI "#define \fBEVUTIL_EAI_NONAME\fP -908"
251 .br
252 .ti -1c
253 .RI "#define \fBEVUTIL_EAI_SERVICE\fP -909"
254 .br
255 .ti -1c
256 .RI "#define \fBEVUTIL_EAI_SOCKTYPE\fP -910"
257 .br
258 .ti -1c
259 .RI "#define \fBEVUTIL_EAI_SYSTEM\fP -911"
260 .br
261 .ti -1c
262 .RI "#define \fBEVUTIL_EAI_CANCEL\fP -90001"
263 .br
264 .ti -1c
265 .RI "#define \fBEVUTIL_AI_PASSIVE\fP 0x1000"
266 .br
267 .ti -1c
268 .RI "#define \fBEVUTIL_AI_CANONNAME\fP 0x2000"
269 .br
270 .ti -1c
271 .RI "#define \fBEVUTIL_AI_NUMERICHOST\fP 0x4000"
272 .br
273 .ti -1c
274 .RI "#define \fBEVUTIL_AI_NUMERICSERV\fP 0x8000"
275 .br
276 .ti -1c
277 .RI "#define \fBEVUTIL_AI_V4MAPPED\fP 0x10000"
278 .br
279 .ti -1c
280 .RI "#define \fBEVUTIL_AI_ALL\fP 0x20000"
281 .br
282 .ti -1c
283 .RI "#define \fBEVUTIL_AI_ADDRCONFIG\fP 0x40000"
284 .br
285 .in -1c
286 .in -1c
287 .SS "Functions"
289 .in +1c
290 .ti -1c
291 .RI "int \fBevutil_ascii_strcasecmp\fP (const char *str1, const char *str2)"
292 .br
293 .RI "\fIAs strcasecmp, but always compares the characters in locale-independent ASCII\&. \fP"
294 .ti -1c
295 .RI "int \fBevutil_ascii_strncasecmp\fP (const char *str1, const char *str2, size_t n)"
296 .br
297 .RI "\fIAs strncasecmp, but always compares the characters in locale-independent ASCII\&. \fP"
298 .ti -1c
299 .RI "int \fBevutil_closesocket\fP (\fBevutil_socket_t\fP sock)"
300 .br
301 .RI "\fIDo the platform-specific call needed to close a socket returned from socket() or accept()\&. \fP"
302 .ti -1c
303 .RI "void \fBevutil_freeaddrinfo\fP (struct \fBevutil_addrinfo\fP *ai)"
304 .br
305 .RI "\fIRelease storage allocated by evutil_getaddrinfo or evdns_getaddrinfo\&. \fP"
306 .ti -1c
307 .RI "const char * \fBevutil_gai_strerror\fP (int err)"
308 .br
309 .ti -1c
310 .RI "int \fBevutil_getaddrinfo\fP (const char *nodename, const char *servname, const struct \fBevutil_addrinfo\fP *hints_in, struct \fBevutil_addrinfo\fP **res)"
311 .br
312 .RI "\fIThis function clones getaddrinfo for systems that don't have it\&. \fP"
313 .ti -1c
314 .RI "int \fBevutil_gettimeofday\fP (struct timeval *tv, struct timezone *tz)"
315 .br
316 .ti -1c
317 .RI "const char * \fBevutil_inet_ntop\fP (int af, const void *src, char *dst, size_t len)"
318 .br
319 .RI "\fIReplacement for inet_ntop for platforms which lack it\&. \fP"
320 .ti -1c
321 .RI "int \fBevutil_inet_pton\fP (int af, const char *src, void *dst)"
322 .br
323 .RI "\fIReplacement for inet_pton for platforms which lack it\&. \fP"
324 .ti -1c
325 .RI "int \fBevutil_make_listen_socket_reuseable\fP (\fBevutil_socket_t\fP sock)"
326 .br
327 .RI "\fIDo platform-specific operations to make a listener socket reusable\&. \fP"
328 .ti -1c
329 .RI "int \fBevutil_make_socket_closeonexec\fP (\fBevutil_socket_t\fP sock)"
330 .br
331 .RI "\fIDo platform-specific operations as needed to close a socket upon a successful execution of one of the exec*() functions\&. \fP"
332 .ti -1c
333 .RI "int \fBevutil_make_socket_nonblocking\fP (\fBevutil_socket_t\fP sock)"
334 .br
335 .RI "\fIDo platform-specific operations as needed to make a socket nonblocking\&. \fP"
336 .ti -1c
337 .RI "int \fBevutil_parse_sockaddr_port\fP (const char *str, struct sockaddr *out, int *outlen)"
338 .br
339 .RI "\fIParse an IPv4 or IPv6 address, with optional port, from a string\&. \fP"
340 .ti -1c
341 .RI "void \fBevutil_secure_rng_add_bytes\fP (const char *dat, size_t datlen)"
342 .br
343 .RI "\fISeed the random number generator with extra random bytes\&. \fP"
344 .ti -1c
345 .RI "void \fBevutil_secure_rng_get_bytes\fP (void *buf, size_t n)"
346 .br
347 .RI "\fIGenerate n bytes of secure pseudorandom data, and store them in buf\&. \fP"
348 .ti -1c
349 .RI "int \fBevutil_secure_rng_init\fP (void)"
350 .br
351 .RI "\fISeed the secure random number generator if needed, and return 0 on success or -1 on failure\&. \fP"
352 .ti -1c
353 .RI "int \fBevutil_secure_rng_set_urandom_device_file\fP (char *fname)"
354 .br
355 .RI "\fISet a filename to use in place of /dev/urandom for seeding the secure PRNG\&. \fP"
356 .ti -1c
357 .RI "int \fBevutil_snprintf\fP (char *buf, size_t buflen, const char *format,\&.\&.\&.)"
358 .br
359 .RI "\fIReplacement for snprintf to get consistent behavior on platforms for which the return value of snprintf does not conform to C99\&. \fP"
360 .ti -1c
361 .RI "int \fBevutil_sockaddr_cmp\fP (const struct sockaddr *sa1, const struct sockaddr *sa2, int include_port)"
362 .br
363 .RI "\fICompare two sockaddrs; return 0 if they are equal, or less than 0 if sa1 preceeds sa2, or greater than 0 if sa1 follows sa2\&. \fP"
364 .ti -1c
365 .RI "int \fBevutil_socketpair\fP (int d, int type, int protocol, \fBevutil_socket_t\fP sv[2])"
366 .br
367 .RI "\fICreate two new sockets that are connected to each other\&. \fP"
368 .ti -1c
369 .RI "ev_int64_t \fBevutil_strtoll\fP (const char *s, char **endptr, int base)"
370 .br
371 .RI "\fIParse a 64-bit value from a string\&. \fP"
372 .ti -1c
373 .RI "int \fBevutil_vsnprintf\fP (char *buf, size_t buflen, const char *format, va_list ap)"
374 .br
375 .RI "\fIReplacement for vsnprintf to get consistent behavior on platforms for which the return value of snprintf does not conform to C99\&. \fP"
376 .in -1c
377 .SH "Detailed Description"
378 .PP
379 Common convenience functions for cross-platform portability and related socket manipulations\&.
382 .SH "Macro Definition Documentation"
383 .PP
384 .SS "#define evutil_offsetof(type, field) ((off_t)(&((type *)0)->field))"
386 .PP
387 Replacement for offsetof on platforms that don't define it\&.
388 .SS "#define EVUTIL_SOCKET_ERROR() \&.\&.\&."
390 .PP
391 Return the most recent socket error\&. Not idempotent on all platforms\&.
392 .SS "#define evutil_socket_error_to_string(errcode) \&.\&.\&."
394 .PP
395 Convert a socket error to a string\&.
396 .SS "#define evutil_socket_geterror(sock) \&.\&.\&."
398 .PP
399 Return the most recent socket error to occur on sock\&.
400 .SS "#define evutil_socket_t int"
402 .PP
403 A type wide enough to hold the output of 'socket()' or 'accept()'\&. On Windows, this is an intptr_t; elsewhere, it is an int\&.
404 .SS "#define evutil_timeradd(tvp, uvp, vvp)"
405 \fBValue:\fP
406 .PP
407 .nf
408 do { \
409 (vvp)->tv_sec = (tvp)->tv_sec + (uvp)->tv_sec; \
410 (vvp)->tv_usec = (tvp)->tv_usec + (uvp)->tv_usec; \
411 if ((vvp)->tv_usec >= 1000000) { \
412 (vvp)->tv_sec++; \
413 (vvp)->tv_usec -= 1000000; \
414 } \
415 } while (0)
416 .fi
417 .SS "#define evutil_timercmp(tvp, uvp, cmp)"
418 \fBValue:\fP
419 .PP
420 .nf
421 (((tvp)->tv_sec == (uvp)->tv_sec) ? \
422 ((tvp)->tv_usec cmp (uvp)->tv_usec) : \
423 ((tvp)->tv_sec cmp (uvp)->tv_sec))
424 .fi
425 .PP
426 Return true iff the tvp is related to uvp according to the relational operator cmp\&. Recognized values for cmp are ==, <=, <, >=, and >\&.
427 .SS "#define evutil_timersub(tvp, uvp, vvp)"
428 \fBValue:\fP
429 .PP
430 .nf
431 do { \
432 (vvp)->tv_sec = (tvp)->tv_sec - (uvp)->tv_sec; \
433 (vvp)->tv_usec = (tvp)->tv_usec - (uvp)->tv_usec; \
434 if ((vvp)->tv_usec < 0) { \
435 (vvp)->tv_sec--; \
436 (vvp)->tv_usec += 1000000; \
437 } \
438 } while (0)
439 .fi
440 .SH "Function Documentation"
441 .PP
442 .SS "int evutil_ascii_strcasecmp (const char *str1, const char *str2)"
444 .PP
445 As strcasecmp, but always compares the characters in locale-independent ASCII\&. That's useful if you're handling data in ASCII-based protocols\&.
446 .SS "int evutil_ascii_strncasecmp (const char *str1, const char *str2, size_tn)"
448 .PP
449 As strncasecmp, but always compares the characters in locale-independent ASCII\&. That's useful if you're handling data in ASCII-based protocols\&.
450 .SS "int evutil_closesocket (\fBevutil_socket_t\fPsock)"
452 .PP
453 Do the platform-specific call needed to close a socket returned from socket() or accept()\&.
454 .PP
455 \fBParameters:\fP
456 .RS 4
457 \fIsock\fP The socket to be closed
458 .RE
459 .PP
460 \fBReturns:\fP
461 .RS 4
462 0 on success, -1 on failure
463 .RE
464 .PP
466 .SS "void evutil_freeaddrinfo (struct \fBevutil_addrinfo\fP *ai)"
468 .PP
469 Release storage allocated by evutil_getaddrinfo or evdns_getaddrinfo\&.
470 .SS "int evutil_getaddrinfo (const char *nodename, const char *servname, const struct \fBevutil_addrinfo\fP *hints_in, struct \fBevutil_addrinfo\fP **res)"
472 .PP
473 This function clones getaddrinfo for systems that don't have it\&. For full details, see RFC 3493, section 6\&.1\&.
474 .PP
475 Limitations:
476 .IP "\(bu" 2
477 When the system has no getaddrinfo, we fall back to gethostbyname_r or gethostbyname, with their attendant issues\&.
478 .IP "\(bu" 2
479 The AI_V4MAPPED and AI_ALL flags are not currently implemented\&.
480 .PP
481 .PP
482 For a nonblocking variant, see evdns_getaddrinfo\&.
483 .SS "const char* evutil_inet_ntop (intaf, const void *src, char *dst, size_tlen)"
485 .PP
486 Replacement for inet_ntop for platforms which lack it\&.
487 .SS "int evutil_inet_pton (intaf, const char *src, void *dst)"
489 .PP
490 Replacement for inet_pton for platforms which lack it\&.
491 .SS "int evutil_make_listen_socket_reuseable (\fBevutil_socket_t\fPsock)"
493 .PP
494 Do platform-specific operations to make a listener socket reusable\&. Specifically, we want to make sure that another program will be able to bind this address right after we've closed the listener\&.
495 .PP
496 This differs from Windows's interpretation of 'reusable', which allows multiple listeners to bind the same address at the same time\&.
497 .PP
498 \fBParameters:\fP
499 .RS 4
500 \fIsock\fP The socket to make reusable
501 .RE
502 .PP
503 \fBReturns:\fP
504 .RS 4
505 0 on success, -1 on failure
506 .RE
507 .PP
509 .SS "int evutil_make_socket_closeonexec (\fBevutil_socket_t\fPsock)"
511 .PP
512 Do platform-specific operations as needed to close a socket upon a successful execution of one of the exec*() functions\&.
513 .PP
514 \fBParameters:\fP
515 .RS 4
516 \fIsock\fP The socket to be closed
517 .RE
518 .PP
519 \fBReturns:\fP
520 .RS 4
521 0 on success, -1 on failure
522 .RE
523 .PP
525 .SS "int evutil_make_socket_nonblocking (\fBevutil_socket_t\fPsock)"
527 .PP
528 Do platform-specific operations as needed to make a socket nonblocking\&.
529 .PP
530 \fBParameters:\fP
531 .RS 4
532 \fIsock\fP The socket to make nonblocking
533 .RE
534 .PP
535 \fBReturns:\fP
536 .RS 4
537 0 on success, -1 on failure
538 .RE
539 .PP
541 .SS "int evutil_parse_sockaddr_port (const char *str, struct sockaddr *out, int *outlen)"
543 .PP
544 Parse an IPv4 or IPv6 address, with optional port, from a string\&. Recognized formats are:
545 .IP "\(bu" 2
546 [IPv6Address]:port
547 .IP "\(bu" 2
548 [IPv6Address]
549 .IP "\(bu" 2
550 IPv6Address
551 .IP "\(bu" 2
552 IPv4Address:port
553 .IP "\(bu" 2
554 IPv4Address
555 .PP
556 .PP
557 If no port is specified, the port in the output is set to 0\&.
558 .PP
559 \fBParameters:\fP
560 .RS 4
561 \fIstr\fP The string to parse\&.
562 .br
563 \fIout\fP A struct sockaddr to hold the result\&. This should probably be a struct sockaddr_storage\&.
564 .br
565 \fIoutlen\fP A pointer to the number of bytes that that 'out' can safely hold\&. Set to the number of bytes used in 'out' on success\&.
566 .RE
567 .PP
568 \fBReturns:\fP
569 .RS 4
570 -1 if the address is not well-formed, if the port is out of range, or if out is not large enough to hold the result\&. Otherwise returns 0 on success\&.
571 .RE
572 .PP
574 .SS "void evutil_secure_rng_add_bytes (const char *dat, size_tdatlen)"
576 .PP
577 Seed the random number generator with extra random bytes\&. You should almost never need to call this function; it should be sufficient to invoke \fBevutil_secure_rng_init()\fP, or let Libevent take care of calling \fBevutil_secure_rng_init()\fP on its own\&.
578 .PP
579 If you call this function as a \fIreplacement\fP for the regular entropy sources, then you need to be sure that your input contains a fairly large amount of strong entropy\&. Doing so is notoriously hard: most people who try get it wrong\&. Watch out!
580 .PP
581 \fBParameters:\fP
582 .RS 4
583 \fIdat\fP a buffer full of a strong source of random numbers
584 .br
585 \fIdatlen\fP the number of bytes to read from datlen
586 .RE
587 .PP
589 .SS "void evutil_secure_rng_get_bytes (void *buf, size_tn)"
591 .PP
592 Generate n bytes of secure pseudorandom data, and store them in buf\&. Current versions of Libevent use an ARC4-based random number generator, seeded using the platform's entropy source (/dev/urandom on Unix-like systems; CryptGenRandom on Windows)\&. This is not actually as secure as it should be: ARC4 is a pretty lousy cipher, and the current implementation provides only rudimentary prediction- and backtracking-resistance\&. Don't use this for serious cryptographic applications\&.
593 .SS "int evutil_secure_rng_init (void)"
595 .PP
596 Seed the secure random number generator if needed, and return 0 on success or -1 on failure\&. It is okay to call this function more than once; it will still return 0 if the RNG has been successfully seeded and -1 if it can't be seeded\&.
597 .PP
598 Ordinarily you don't need to call this function from your own code; Libevent will seed the RNG itself the first time it needs good random numbers\&. You only need to call it if (a) you want to double-check that one of the seeding methods did succeed, or (b) you plan to drop the capability to seed (by chrooting, or dropping capabilities, or whatever), and you want to make sure that seeding happens before your program loses the ability to do it\&.
599 .SS "int evutil_secure_rng_set_urandom_device_file (char *fname)"
601 .PP
602 Set a filename to use in place of /dev/urandom for seeding the secure PRNG\&. Return 0 on success, -1 on failure\&.
603 .PP
604 Call this function BEFORE calling any other initialization or RNG functions\&.
605 .PP
606 (This string will \fINOT\fP be copied internally\&. Do not free it while any user of the secure RNG might be running\&. Don't pass anything other than a real /dev/\&.\&.\&.random device file here, or you might lose security\&.)
607 .PP
608 This API is unstable, and might change in a future libevent version\&.
609 .SS "int evutil_sockaddr_cmp (const struct sockaddr *sa1, const struct sockaddr *sa2, intinclude_port)"
611 .PP
612 Compare two sockaddrs; return 0 if they are equal, or less than 0 if sa1 preceeds sa2, or greater than 0 if sa1 follows sa2\&. If include_port is true, consider the port as well as the address\&. Only implemented for AF_INET and AF_INET6 addresses\&. The ordering is not guaranteed to remain the same between Libevent versions\&.
613 .SS "int evutil_socketpair (intd, inttype, intprotocol, \fBevutil_socket_t\fPsv[2])"
615 .PP
616 Create two new sockets that are connected to each other\&. On Unix, this simply calls socketpair()\&. On Windows, it uses the loopback network interface on 127\&.0\&.0\&.1, and only AF_INET,SOCK_STREAM are supported\&.
617 .PP
618 (This may fail on some Windows hosts where firewall software has cleverly decided to keep 127\&.0\&.0\&.1 from talking to itself\&.)
619 .PP
620 Parameters and return values are as for socketpair()
621 .SS "ev_int64_t evutil_strtoll (const char *s, char **endptr, intbase)"
623 .PP
624 Parse a 64-bit value from a string\&. Arguments are as for strtol\&.
625 .SH "Author"
626 .PP
627 Generated automatically by Doxygen for libevent from the source code\&.