1 /*
2  * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * 1. Redistributions of source code must retain the above copyright
8  *    notice, this list of conditions and the following disclaimer.
9  * 2. Redistributions in binary form must reproduce the above copyright
10  *    notice, this list of conditions and the following disclaimer in the
11  *    documentation and/or other materials provided with the distribution.
12  * 3. The name of the author may not be used to endorse or promote products
13  *    derived from this software without specific prior written permission.
14  *
15  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
16  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
17  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
18  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
19  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
20  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
21  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
22  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
24  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
25  */
26 #ifndef EVENT2_UTIL_H_INCLUDED_
27 #define EVENT2_UTIL_H_INCLUDED_
28 
29 /** @file event2/util.h
30 
31   Common convenience functions for cross-platform portability and
32   related socket manipulations.
33 
34  */
35 #include <event2/visibility.h>
36 
37 #ifdef __cplusplus
38 extern "C" {
39 #endif
40 
41 #include <event2/event-config.h>
42 #ifdef EVENT__HAVE_SYS_TIME_H
43 #include <sys/time.h>
44 #endif
45 #ifdef EVENT__HAVE_STDINT_H
46 #include <stdint.h>
47 #elif defined(EVENT__HAVE_INTTYPES_H)
48 #include <inttypes.h>
49 #endif
50 #ifdef EVENT__HAVE_SYS_TYPES_H
51 #include <sys/types.h>
52 #endif
53 #ifdef EVENT__HAVE_STDDEF_H
54 #include <stddef.h>
55 #endif
56 #ifdef _MSC_VER
57 #include <BaseTsd.h>
58 #endif
59 #include <stdarg.h>
60 #ifdef EVENT__HAVE_NETDB_H
61 #if !defined(_GNU_SOURCE)
62 #define _GNU_SOURCE
63 #endif
64 #include <netdb.h>
65 #endif
66 
67 #ifdef _WIN32
68 #include <winsock2.h>
69 #ifdef EVENT__HAVE_GETADDRINFO
70 /* for EAI_* definitions. */
71 #include <ws2tcpip.h>
72 #endif
73 #else
74 #ifdef EVENT__HAVE_ERRNO_H
75 #include <errno.h>
76 #endif
77 #include <sys/socket.h>
78 #endif
79 
80 #include <time.h>
81 
82 /* Some openbsd autoconf versions get the name of this macro wrong. */
83 #if defined(EVENT__SIZEOF_VOID__) && !defined(EVENT__SIZEOF_VOID_P)
84 #define EVENT__SIZEOF_VOID_P EVENT__SIZEOF_VOID__
85 #endif
86 
87 /**
88  * @name Standard integer types.
89  *
90  * Integer type definitions for types that are supposed to be defined in the
91  * C99-specified stdint.h.  Shamefully, some platforms do not include
92  * stdint.h, so we need to replace it.  (If you are on a platform like this,
93  * your C headers are now over 10 years out of date.  You should bug them to
94  * do something about this.)
95  *
96  * We define:
97  *
98  * <dl>
99  *   <dt>ev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t</dt>
100  *      <dd>unsigned integer types of exactly 64, 32, 16, and 8 bits
101  *          respectively.</dd>
102  *    <dt>ev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t</dt>
103  *      <dd>signed integer types of exactly 64, 32, 16, and 8 bits
104  *          respectively.</dd>
105  *    <dt>ev_uintptr_t, ev_intptr_t</dt>
106  *      <dd>unsigned/signed integers large enough
107  *      to hold a pointer without loss of bits.</dd>
108  *    <dt>ev_ssize_t</dt>
109  *      <dd>A signed type of the same size as size_t</dd>
110  *    <dt>ev_off_t</dt>
111  *      <dd>A signed type typically used to represent offsets within a
112  *      (potentially large) file</dd>
113  *
114  * @{
115  */
116 #ifdef EVENT__HAVE_UINT64_T
117 #define ev_uint64_t uint64_t
118 #define ev_int64_t int64_t
119 #elif defined(_WIN32)
120 #define ev_uint64_t unsigned __int64
121 #define ev_int64_t signed __int64
122 #elif EVENT__SIZEOF_LONG_LONG == 8
123 #define ev_uint64_t unsigned long long
124 #define ev_int64_t long long
125 #elif EVENT__SIZEOF_LONG == 8
126 #define ev_uint64_t unsigned long
127 #define ev_int64_t long
128 #elif defined(EVENT_IN_DOXYGEN_)
129 #define ev_uint64_t ...
130 #define ev_int64_t ...
131 #else
132 #error "No way to define ev_uint64_t"
133 #endif
134 
135 #ifdef EVENT__HAVE_UINT32_T
136 #define ev_uint32_t uint32_t
137 #define ev_int32_t int32_t
138 #elif defined(_WIN32)
139 #define ev_uint32_t unsigned int
140 #define ev_int32_t signed int
141 #elif EVENT__SIZEOF_LONG == 4
142 #define ev_uint32_t unsigned long
143 #define ev_int32_t signed long
144 #elif EVENT__SIZEOF_INT == 4
145 #define ev_uint32_t unsigned int
146 #define ev_int32_t signed int
147 #elif defined(EVENT_IN_DOXYGEN_)
148 #define ev_uint32_t ...
149 #define ev_int32_t ...
150 #else
151 #error "No way to define ev_uint32_t"
152 #endif
153 
154 #ifdef EVENT__HAVE_UINT16_T
155 #define ev_uint16_t uint16_t
156 #define ev_int16_t  int16_t
157 #elif defined(_WIN32)
158 #define ev_uint16_t unsigned short
159 #define ev_int16_t  signed short
160 #elif EVENT__SIZEOF_INT == 2
161 #define ev_uint16_t unsigned int
162 #define ev_int16_t  signed int
163 #elif EVENT__SIZEOF_SHORT == 2
164 #define ev_uint16_t unsigned short
165 #define ev_int16_t  signed short
166 #elif defined(EVENT_IN_DOXYGEN_)
167 #define ev_uint16_t ...
168 #define ev_int16_t ...
169 #else
170 #error "No way to define ev_uint16_t"
171 #endif
172 
173 #ifdef EVENT__HAVE_UINT8_T
174 #define ev_uint8_t uint8_t
175 #define ev_int8_t int8_t
176 #elif defined(EVENT_IN_DOXYGEN_)
177 #define ev_uint8_t ...
178 #define ev_int8_t ...
179 #else
180 #define ev_uint8_t unsigned char
181 #define ev_int8_t signed char
182 #endif
183 
184 #ifdef EVENT__HAVE_UINTPTR_T
185 #define ev_uintptr_t uintptr_t
186 #define ev_intptr_t intptr_t
187 #elif EVENT__SIZEOF_VOID_P <= 4
188 #define ev_uintptr_t ev_uint32_t
189 #define ev_intptr_t ev_int32_t
190 #elif EVENT__SIZEOF_VOID_P <= 8
191 #define ev_uintptr_t ev_uint64_t
192 #define ev_intptr_t ev_int64_t
193 #elif defined(EVENT_IN_DOXYGEN_)
194 #define ev_uintptr_t ...
195 #define ev_intptr_t ...
196 #else
197 #error "No way to define ev_uintptr_t"
198 #endif
199 
200 #ifdef EVENT__ssize_t
201 #define ev_ssize_t EVENT__ssize_t
202 #else
203 #define ev_ssize_t ssize_t
204 #endif
205 
206 /* Note that we define ev_off_t based on the compile-time size of off_t that
207  * we used to build Libevent, and not based on the current size of off_t.
208  * (For example, we don't define ev_off_t to off_t.).  We do this because
209  * some systems let you build your software with different off_t sizes
210  * at runtime, and so putting in any dependency on off_t would risk API
211  * mismatch.
212  */
213 #ifdef _WIN32
214 #define ev_off_t ev_int64_t
215 #elif EVENT__SIZEOF_OFF_T == 8
216 #define ev_off_t ev_int64_t
217 #elif EVENT__SIZEOF_OFF_T == 4
218 #define ev_off_t ev_int32_t
219 #elif defined(EVENT_IN_DOXYGEN_)
220 #define ev_off_t ...
221 #else
222 #define ev_off_t off_t
223 #endif
224 /**@}*/
225 
226 /* Limits for integer types.
227 
228    We're making two assumptions here:
229      - The compiler does constant folding properly.
230      - The platform does signed arithmetic in two's complement.
231 */
232 
233 /**
234    @name Limits for integer types
235 
236    These macros hold the largest or smallest values possible for the
237    ev_[u]int*_t types.
238 
239    @{
240 */
241 #ifndef EVENT__HAVE_STDINT_H
242 #define EV_UINT64_MAX ((((ev_uint64_t)0xffffffffUL) << 32) | 0xffffffffUL)
243 #define EV_INT64_MAX  ((((ev_int64_t) 0x7fffffffL) << 32) | 0xffffffffL)
244 #define EV_INT64_MIN  ((-EV_INT64_MAX) - 1)
245 #define EV_UINT32_MAX ((ev_uint32_t)0xffffffffUL)
246 #define EV_INT32_MAX  ((ev_int32_t) 0x7fffffffL)
247 #define EV_INT32_MIN  ((-EV_INT32_MAX) - 1)
248 #define EV_UINT16_MAX ((ev_uint16_t)0xffffUL)
249 #define EV_INT16_MAX  ((ev_int16_t) 0x7fffL)
250 #define EV_INT16_MIN  ((-EV_INT16_MAX) - 1)
251 #define EV_UINT8_MAX  255
252 #define EV_INT8_MAX   127
253 #define EV_INT8_MIN   ((-EV_INT8_MAX) - 1)
254 #else
255 #define EV_UINT64_MAX UINT64_MAX
256 #define EV_INT64_MAX  INT64_MAX
257 #define EV_INT64_MIN  INT64_MIN
258 #define EV_UINT32_MAX UINT32_MAX
259 #define EV_INT32_MAX  INT32_MAX
260 #define EV_INT32_MIN  INT32_MIN
261 #define EV_UINT16_MAX UINT16_MAX
262 #define EV_INT16_MAX  INT16_MAX
263 #define EV_UINT8_MAX  UINT8_MAX
264 #define EV_INT8_MAX   INT8_MAX
265 #define EV_INT8_MIN   INT8_MIN
266 /** @} */
267 #endif
268 
269 
270 /**
271    @name Limits for SIZE_T and SSIZE_T
272 
273    @{
274 */
275 #if EVENT__SIZEOF_SIZE_T == 8
276 #define EV_SIZE_MAX EV_UINT64_MAX
277 #define EV_SSIZE_MAX EV_INT64_MAX
278 #elif EVENT__SIZEOF_SIZE_T == 4
279 #define EV_SIZE_MAX EV_UINT32_MAX
280 #define EV_SSIZE_MAX EV_INT32_MAX
281 #elif defined(EVENT_IN_DOXYGEN_)
282 #define EV_SIZE_MAX ...
283 #define EV_SSIZE_MAX ...
284 #else
285 #error "No way to define SIZE_MAX"
286 #endif
287 
288 #define EV_SSIZE_MIN ((-EV_SSIZE_MAX) - 1)
289 /**@}*/
290 
291 #ifdef _WIN32
292 #define ev_socklen_t int
293 #elif defined(EVENT__socklen_t)
294 #define ev_socklen_t EVENT__socklen_t
295 #else
296 #define ev_socklen_t socklen_t
297 #endif
298 
299 #ifdef EVENT__HAVE_STRUCT_SOCKADDR_STORAGE___SS_FAMILY
300 #if !defined(EVENT__HAVE_STRUCT_SOCKADDR_STORAGE_SS_FAMILY) \
301  && !defined(ss_family)
302 #define ss_family __ss_family
303 #endif
304 #endif
305 
306 /**
307  * A type wide enough to hold the output of "socket()" or "accept()".  On
308  * Windows, this is an intptr_t; elsewhere, it is an int. */
309 #ifdef _WIN32
310 #define evutil_socket_t intptr_t
311 #else
312 #define evutil_socket_t int
313 #endif
314 
315 /**
316  * Structure to hold information about a monotonic timer
317  *
318  * Use this with evutil_configure_monotonic_time() and
319  * evutil_gettime_monotonic().
320  *
321  * This is an opaque structure; you can allocate one using
322  * evutil_monotonic_timer_new().
323  *
324  * @see evutil_monotonic_timer_new(), evutil_monotonic_timer_free(),
325  * evutil_configure_monotonic_time(), evutil_gettime_monotonic()
326  */
327 struct evutil_monotonic_timer
328 #ifdef EVENT_IN_DOXYGEN_
329 {/*Empty body so that doxygen will generate documentation here.*/}
330 #endif
331 ;
332 
333 #define EV_MONOT_PRECISE  1
334 #define EV_MONOT_FALLBACK 2
335 
336 /** Format a date string using RFC 1123 format (used in HTTP).
337  * If `tm` is NULL, current system's time will be used.
338  * The number of characters written will be returned.
339  * One should check if the return value is smaller than `datelen` to check if
340  * the result is truncated or not.
341  */
342 EVENT2_EXPORT_SYMBOL int
343 evutil_date_rfc1123(char *date, const size_t datelen, const struct tm *tm);
344 
345 /** Allocate a new struct evutil_monotonic_timer for use with the
346  * evutil_configure_monotonic_time() and evutil_gettime_monotonic()
347  * functions.  You must configure the timer with
348  * evutil_configure_monotonic_time() before using it.
349  */
350 EVENT2_EXPORT_SYMBOL
351 struct evutil_monotonic_timer * evutil_monotonic_timer_new(void);
352 
353 /** Free a struct evutil_monotonic_timer that was allocated using
354  * evutil_monotonic_timer_new().
355  */
356 EVENT2_EXPORT_SYMBOL
357 void evutil_monotonic_timer_free(struct evutil_monotonic_timer *timer);
358 
359 /** Set up a struct evutil_monotonic_timer; flags can include
360  * EV_MONOT_PRECISE and EV_MONOT_FALLBACK.
361  */
362 EVENT2_EXPORT_SYMBOL
363 int evutil_configure_monotonic_time(struct evutil_monotonic_timer *timer,
364                                     int flags);
365 
366 /** Query the current monotonic time from a struct evutil_monotonic_timer
367  * previously configured with evutil_configure_monotonic_time().  Monotonic
368  * time is guaranteed never to run in reverse, but is not necessarily epoch-
369  * based, or relative to any other definite point.  Use it to make reliable
370  * measurements of elapsed time between events even when the system time
371  * may be changed.
372  *
373  * It is not safe to use this funtion on the same timer from multiple
374  * threads.
375  */
376 EVENT2_EXPORT_SYMBOL
377 int evutil_gettime_monotonic(struct evutil_monotonic_timer *timer,
378                              struct timeval *tp);
379 
380 /** Create two new sockets that are connected to each other.
381 
382     On Unix, this simply calls socketpair().  On Windows, it uses the
383     loopback network interface on 127.0.0.1, and only
384     AF_INET,SOCK_STREAM are supported.
385 
386     (This may fail on some Windows hosts where firewall software has cleverly
387     decided to keep 127.0.0.1 from talking to itself.)
388 
389     Parameters and return values are as for socketpair()
390 */
391 EVENT2_EXPORT_SYMBOL
392 int evutil_socketpair(int d, int type, int protocol, evutil_socket_t sv[2]);
393 /** Do platform-specific operations as needed to make a socket nonblocking.
394 
395     @param sock The socket to make nonblocking
396     @return 0 on success, -1 on failure
397  */
398 EVENT2_EXPORT_SYMBOL
399 int evutil_make_socket_nonblocking(evutil_socket_t sock);
400 
401 /** Do platform-specific operations to make a listener socket reusable.
402 
403     Specifically, we want to make sure that another program will be able
404     to bind this address right after we've closed the listener.
405 
406     This differs from Windows's interpretation of "reusable", which
407     allows multiple listeners to bind the same address at the same time.
408 
409     @param sock The socket to make reusable
410     @return 0 on success, -1 on failure
411  */
412 EVENT2_EXPORT_SYMBOL
413 int evutil_make_listen_socket_reuseable(evutil_socket_t sock);
414 
415 /** Do platform-specific operations to make a listener port reusable.
416 
417     Specifically, we want to make sure that multiple programs which also
418     set the same socket option will be able to bind, listen at the same time.
419 
420     This is a feature available only to Linux 3.9+
421 
422     @param sock The socket to make reusable
423     @return 0 on success, -1 on failure
424  */
425 EVENT2_EXPORT_SYMBOL
426 int evutil_make_listen_socket_reuseable_port(evutil_socket_t sock);
427 
428 /** Do platform-specific operations as needed to close a socket upon a
429     successful execution of one of the exec*() functions.
430 
431     @param sock The socket to be closed
432     @return 0 on success, -1 on failure
433  */
434 EVENT2_EXPORT_SYMBOL
435 int evutil_make_socket_closeonexec(evutil_socket_t sock);
436 
437 /** Do the platform-specific call needed to close a socket returned from
438     socket() or accept().
439 
440     @param sock The socket to be closed
441     @return 0 on success, -1 on failure
442  */
443 EVENT2_EXPORT_SYMBOL
444 int evutil_closesocket(evutil_socket_t sock);
445 #define EVUTIL_CLOSESOCKET(s) evutil_closesocket(s)
446 
447 /** Do platform-specific operations, if possible, to make a tcp listener
448  *  socket defer accept()s until there is data to read.
449  *
450  *  Not all platforms support this.  You don't want to do this for every
451  *  listener socket: only the ones that implement a protocol where the
452  *  client transmits before the server needs to respond.
453  *
454  *  @param sock The listening socket to to make deferred
455  *  @return 0 on success (whether the operation is supported or not),
456  *       -1 on failure
457 */
458 EVENT2_EXPORT_SYMBOL
459 int evutil_make_tcp_listen_socket_deferred(evutil_socket_t sock);
460 
461 #ifdef _WIN32
462 /** Return the most recent socket error.  Not idempotent on all platforms. */
463 #define EVUTIL_SOCKET_ERROR() WSAGetLastError()
464 /** Replace the most recent socket error with errcode */
465 #define EVUTIL_SET_SOCKET_ERROR(errcode)		\
466 	do { WSASetLastError(errcode); } while (0)
467 /** Return the most recent socket error to occur on sock. */
468 EVENT2_EXPORT_SYMBOL
469 int evutil_socket_geterror(evutil_socket_t sock);
470 /** Convert a socket error to a string. */
471 EVENT2_EXPORT_SYMBOL
472 const char *evutil_socket_error_to_string(int errcode);
473 #elif defined(EVENT_IN_DOXYGEN_)
474 /**
475    @name Socket error functions
476 
477    These functions are needed for making programs compatible between
478    Windows and Unix-like platforms.
479 
480    You see, Winsock handles socket errors differently from the rest of
481    the world.  Elsewhere, a socket error is like any other error and is
482    stored in errno.  But winsock functions require you to retrieve the
483    error with a special function, and don't let you use strerror for
484    the error codes.  And handling EWOULDBLOCK is ... different.
485 
486    @{
487 */
488 /** Return the most recent socket error.  Not idempotent on all platforms. */
489 #define EVUTIL_SOCKET_ERROR() ...
490 /** Replace the most recent socket error with errcode */
491 #define EVUTIL_SET_SOCKET_ERROR(errcode) ...
492 /** Return the most recent socket error to occur on sock. */
493 #define evutil_socket_geterror(sock) ...
494 /** Convert a socket error to a string. */
495 #define evutil_socket_error_to_string(errcode) ...
496 /**@}*/
497 #else
498 #define EVUTIL_SOCKET_ERROR() (errno)
499 #define EVUTIL_SET_SOCKET_ERROR(errcode)		\
500 		do { errno = (errcode); } while (0)
501 #define evutil_socket_geterror(sock) (errno)
502 #define evutil_socket_error_to_string(errcode) (strerror(errcode))
503 #endif
504 
505 
506 /**
507  * @name Manipulation macros for struct timeval.
508  *
509  * We define replacements
510  * for timeradd, timersub, timerclear, timercmp, and timerisset.
511  *
512  * @{
513  */
514 #ifdef EVENT__HAVE_TIMERADD
515 #define evutil_timeradd(tvp, uvp, vvp) timeradd((tvp), (uvp), (vvp))
516 #define evutil_timersub(tvp, uvp, vvp) timersub((tvp), (uvp), (vvp))
517 #else
518 #define evutil_timeradd(tvp, uvp, vvp)					\
519 	do {								\
520 		(vvp)->tv_sec = (tvp)->tv_sec + (uvp)->tv_sec;		\
521 		(vvp)->tv_usec = (tvp)->tv_usec + (uvp)->tv_usec;       \
522 		if ((vvp)->tv_usec >= 1000000) {			\
523 			(vvp)->tv_sec++;				\
524 			(vvp)->tv_usec -= 1000000;			\
525 		}							\
526 	} while (0)
527 #define	evutil_timersub(tvp, uvp, vvp)					\
528 	do {								\
529 		(vvp)->tv_sec = (tvp)->tv_sec - (uvp)->tv_sec;		\
530 		(vvp)->tv_usec = (tvp)->tv_usec - (uvp)->tv_usec;	\
531 		if ((vvp)->tv_usec < 0) {				\
532 			(vvp)->tv_sec--;				\
533 			(vvp)->tv_usec += 1000000;			\
534 		}							\
535 	} while (0)
536 #endif /* !EVENT__HAVE_TIMERADD */
537 
538 #ifdef EVENT__HAVE_TIMERCLEAR
539 #define evutil_timerclear(tvp) timerclear(tvp)
540 #else
541 #define	evutil_timerclear(tvp)	(tvp)->tv_sec = (tvp)->tv_usec = 0
542 #endif
543 /**@}*/
544 
545 /** Return true iff the tvp is related to uvp according to the relational
546  * operator cmp.  Recognized values for cmp are ==, <=, <, >=, and >. */
547 #define	evutil_timercmp(tvp, uvp, cmp)					\
548 	(((tvp)->tv_sec == (uvp)->tv_sec) ?				\
549 	 ((tvp)->tv_usec cmp (uvp)->tv_usec) :				\
550 	 ((tvp)->tv_sec cmp (uvp)->tv_sec))
551 
552 #ifdef EVENT__HAVE_TIMERISSET
553 #define evutil_timerisset(tvp) timerisset(tvp)
554 #else
555 #define	evutil_timerisset(tvp)	((tvp)->tv_sec || (tvp)->tv_usec)
556 #endif
557 
558 /** Replacement for offsetof on platforms that don't define it. */
559 #ifdef offsetof
560 #define evutil_offsetof(type, field) offsetof(type, field)
561 #else
562 #define evutil_offsetof(type, field) ((off_t)(&((type *)0)->field))
563 #endif
564 
565 /* big-int related functions */
566 /** Parse a 64-bit value from a string.  Arguments are as for strtol. */
567 EVENT2_EXPORT_SYMBOL
568 ev_int64_t evutil_strtoll(const char *s, char **endptr, int base);
569 
570 /** Replacement for gettimeofday on platforms that lack it. */
571 #ifdef EVENT__HAVE_GETTIMEOFDAY
572 #define evutil_gettimeofday(tv, tz) gettimeofday((tv), (tz))
573 #else
574 struct timezone;
575 EVENT2_EXPORT_SYMBOL
576 int evutil_gettimeofday(struct timeval *tv, struct timezone *tz);
577 #endif
578 
579 /** Replacement for snprintf to get consistent behavior on platforms for
580     which the return value of snprintf does not conform to C99.
581  */
582 EVENT2_EXPORT_SYMBOL
583 int evutil_snprintf(char *buf, size_t buflen, const char *format, ...)
584 #ifdef __GNUC__
585 	__attribute__((format(printf, 3, 4)))
586 #endif
587 ;
588 /** Replacement for vsnprintf to get consistent behavior on platforms for
589     which the return value of snprintf does not conform to C99.
590  */
591 EVENT2_EXPORT_SYMBOL
592 int evutil_vsnprintf(char *buf, size_t buflen, const char *format, va_list ap)
593 #ifdef __GNUC__
594 	__attribute__((format(printf, 3, 0)))
595 #endif
596 ;
597 
598 /** Replacement for inet_ntop for platforms which lack it. */
599 EVENT2_EXPORT_SYMBOL
600 const char *evutil_inet_ntop(int af, const void *src, char *dst, size_t len);
601 /** Replacement for inet_pton for platforms which lack it. */
602 EVENT2_EXPORT_SYMBOL
603 int evutil_inet_pton(int af, const char *src, void *dst);
604 struct sockaddr;
605 
606 /** Parse an IPv4 or IPv6 address, with optional port, from a string.
607 
608     Recognized formats are:
609     - [IPv6Address]:port
610     - [IPv6Address]
611     - IPv6Address
612     - IPv4Address:port
613     - IPv4Address
614 
615     If no port is specified, the port in the output is set to 0.
616 
617     @param str The string to parse.
618     @param out A struct sockaddr to hold the result.  This should probably be
619        a struct sockaddr_storage.
620     @param outlen A pointer to the number of bytes that that 'out' can safely
621        hold.  Set to the number of bytes used in 'out' on success.
622     @return -1 if the address is not well-formed, if the port is out of range,
623        or if out is not large enough to hold the result.  Otherwise returns
624        0 on success.
625 */
626 EVENT2_EXPORT_SYMBOL
627 int evutil_parse_sockaddr_port(const char *str, struct sockaddr *out, int *outlen);
628 
629 /** Compare two sockaddrs; return 0 if they are equal, or less than 0 if sa1
630  * preceeds sa2, or greater than 0 if sa1 follows sa2.  If include_port is
631  * true, consider the port as well as the address.  Only implemented for
632  * AF_INET and AF_INET6 addresses. The ordering is not guaranteed to remain
633  * the same between Libevent versions. */
634 EVENT2_EXPORT_SYMBOL
635 int evutil_sockaddr_cmp(const struct sockaddr *sa1, const struct sockaddr *sa2,
636     int include_port);
637 
638 /** As strcasecmp, but always compares the characters in locale-independent
639     ASCII.  That's useful if you're handling data in ASCII-based protocols.
640  */
641 EVENT2_EXPORT_SYMBOL
642 int evutil_ascii_strcasecmp(const char *str1, const char *str2);
643 /** As strncasecmp, but always compares the characters in locale-independent
644     ASCII.  That's useful if you're handling data in ASCII-based protocols.
645  */
646 EVENT2_EXPORT_SYMBOL
647 int evutil_ascii_strncasecmp(const char *str1, const char *str2, size_t n);
648 
649 /* Here we define evutil_addrinfo to the native addrinfo type, or redefine it
650  * if this system has no getaddrinfo(). */
651 #ifdef EVENT__HAVE_STRUCT_ADDRINFO
652 #define evutil_addrinfo addrinfo
653 #else
654 /** A definition of struct addrinfo for systems that lack it.
655 
656     (This is just an alias for struct addrinfo if the system defines
657     struct addrinfo.)
658 */
659 struct evutil_addrinfo {
660 	int     ai_flags;     /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
661 	int     ai_family;    /* PF_xxx */
662 	int     ai_socktype;  /* SOCK_xxx */
663 	int     ai_protocol;  /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
664 	size_t  ai_addrlen;   /* length of ai_addr */
665 	char   *ai_canonname; /* canonical name for nodename */
666 	struct sockaddr  *ai_addr; /* binary address */
667 	struct evutil_addrinfo  *ai_next; /* next structure in linked list */
668 };
669 #endif
670 /** @name evutil_getaddrinfo() error codes
671 
672     These values are possible error codes for evutil_getaddrinfo() and
673     related functions.
674 
675     @{
676 */
677 #if defined(EAI_ADDRFAMILY) && defined(EVENT__HAVE_GETADDRINFO)
678 #define EVUTIL_EAI_ADDRFAMILY EAI_ADDRFAMILY
679 #else
680 #define EVUTIL_EAI_ADDRFAMILY -901
681 #endif
682 #if defined(EAI_AGAIN) && defined(EVENT__HAVE_GETADDRINFO)
683 #define EVUTIL_EAI_AGAIN EAI_AGAIN
684 #else
685 #define EVUTIL_EAI_AGAIN -902
686 #endif
687 #if defined(EAI_BADFLAGS) && defined(EVENT__HAVE_GETADDRINFO)
688 #define EVUTIL_EAI_BADFLAGS EAI_BADFLAGS
689 #else
690 #define EVUTIL_EAI_BADFLAGS -903
691 #endif
692 #if defined(EAI_FAIL) && defined(EVENT__HAVE_GETADDRINFO)
693 #define EVUTIL_EAI_FAIL EAI_FAIL
694 #else
695 #define EVUTIL_EAI_FAIL -904
696 #endif
697 #if defined(EAI_FAMILY) && defined(EVENT__HAVE_GETADDRINFO)
698 #define EVUTIL_EAI_FAMILY EAI_FAMILY
699 #else
700 #define EVUTIL_EAI_FAMILY -905
701 #endif
702 #if defined(EAI_MEMORY) && defined(EVENT__HAVE_GETADDRINFO)
703 #define EVUTIL_EAI_MEMORY EAI_MEMORY
704 #else
705 #define EVUTIL_EAI_MEMORY -906
706 #endif
707 /* This test is a bit complicated, since some MS SDKs decide to
708  * remove NODATA or redefine it to be the same as NONAME, in a
709  * fun interpretation of RFC 2553 and RFC 3493. */
710 #if defined(EAI_NODATA) && defined(EVENT__HAVE_GETADDRINFO) && (!defined(EAI_NONAME) || EAI_NODATA != EAI_NONAME)
711 #define EVUTIL_EAI_NODATA EAI_NODATA
712 #else
713 #define EVUTIL_EAI_NODATA -907
714 #endif
715 #if defined(EAI_NONAME) && defined(EVENT__HAVE_GETADDRINFO)
716 #define EVUTIL_EAI_NONAME EAI_NONAME
717 #else
718 #define EVUTIL_EAI_NONAME -908
719 #endif
720 #if defined(EAI_SERVICE) && defined(EVENT__HAVE_GETADDRINFO)
721 #define EVUTIL_EAI_SERVICE EAI_SERVICE
722 #else
723 #define EVUTIL_EAI_SERVICE -909
724 #endif
725 #if defined(EAI_SOCKTYPE) && defined(EVENT__HAVE_GETADDRINFO)
726 #define EVUTIL_EAI_SOCKTYPE EAI_SOCKTYPE
727 #else
728 #define EVUTIL_EAI_SOCKTYPE -910
729 #endif
730 #if defined(EAI_SYSTEM) && defined(EVENT__HAVE_GETADDRINFO)
731 #define EVUTIL_EAI_SYSTEM EAI_SYSTEM
732 #else
733 #define EVUTIL_EAI_SYSTEM -911
734 #endif
735 
736 #define EVUTIL_EAI_CANCEL -90001
737 
738 #if defined(AI_PASSIVE) && defined(EVENT__HAVE_GETADDRINFO)
739 #define EVUTIL_AI_PASSIVE AI_PASSIVE
740 #else
741 #define EVUTIL_AI_PASSIVE 0x1000
742 #endif
743 #if defined(AI_CANONNAME) && defined(EVENT__HAVE_GETADDRINFO)
744 #define EVUTIL_AI_CANONNAME AI_CANONNAME
745 #else
746 #define EVUTIL_AI_CANONNAME 0x2000
747 #endif
748 #if defined(AI_NUMERICHOST) && defined(EVENT__HAVE_GETADDRINFO)
749 #define EVUTIL_AI_NUMERICHOST AI_NUMERICHOST
750 #else
751 #define EVUTIL_AI_NUMERICHOST 0x4000
752 #endif
753 #if defined(AI_NUMERICSERV) && defined(EVENT__HAVE_GETADDRINFO)
754 #define EVUTIL_AI_NUMERICSERV AI_NUMERICSERV
755 #else
756 #define EVUTIL_AI_NUMERICSERV 0x8000
757 #endif
758 #if defined(AI_V4MAPPED) && defined(EVENT__HAVE_GETADDRINFO)
759 #define EVUTIL_AI_V4MAPPED AI_V4MAPPED
760 #else
761 #define EVUTIL_AI_V4MAPPED 0x10000
762 #endif
763 #if defined(AI_ALL) && defined(EVENT__HAVE_GETADDRINFO)
764 #define EVUTIL_AI_ALL AI_ALL
765 #else
766 #define EVUTIL_AI_ALL 0x20000
767 #endif
768 #if defined(AI_ADDRCONFIG) && defined(EVENT__HAVE_GETADDRINFO)
769 #define EVUTIL_AI_ADDRCONFIG AI_ADDRCONFIG
770 #else
771 #define EVUTIL_AI_ADDRCONFIG 0x40000
772 #endif
773 /**@}*/
774 
775 struct evutil_addrinfo;
776 /**
777  * This function clones getaddrinfo for systems that don't have it.  For full
778  * details, see RFC 3493, section 6.1.
779  *
780  * Limitations:
781  * - When the system has no getaddrinfo, we fall back to gethostbyname_r or
782  *   gethostbyname, with their attendant issues.
783  * - The AI_V4MAPPED and AI_ALL flags are not currently implemented.
784  *
785  * For a nonblocking variant, see evdns_getaddrinfo.
786  */
787 EVENT2_EXPORT_SYMBOL
788 int evutil_getaddrinfo(const char *nodename, const char *servname,
789     const struct evutil_addrinfo *hints_in, struct evutil_addrinfo **res);
790 
791 /** Release storage allocated by evutil_getaddrinfo or evdns_getaddrinfo. */
792 EVENT2_EXPORT_SYMBOL
793 void evutil_freeaddrinfo(struct evutil_addrinfo *ai);
794 
795 EVENT2_EXPORT_SYMBOL
796 const char *evutil_gai_strerror(int err);
797 
798 /** Generate n bytes of secure pseudorandom data, and store them in buf.
799  *
800  * Current versions of Libevent use an ARC4-based random number generator,
801  * seeded using the platform's entropy source (/dev/urandom on Unix-like
802  * systems; CryptGenRandom on Windows).  This is not actually as secure as it
803  * should be: ARC4 is a pretty lousy cipher, and the current implementation
804  * provides only rudimentary prediction- and backtracking-resistance.  Don't
805  * use this for serious cryptographic applications.
806  */
807 EVENT2_EXPORT_SYMBOL
808 void evutil_secure_rng_get_bytes(void *buf, size_t n);
809 
810 /**
811  * Seed the secure random number generator if needed, and return 0 on
812  * success or -1 on failure.
813  *
814  * It is okay to call this function more than once; it will still return
815  * 0 if the RNG has been successfully seeded and -1 if it can't be
816  * seeded.
817  *
818  * Ordinarily you don't need to call this function from your own code;
819  * Libevent will seed the RNG itself the first time it needs good random
820  * numbers.  You only need to call it if (a) you want to double-check
821  * that one of the seeding methods did succeed, or (b) you plan to drop
822  * the capability to seed (by chrooting, or dropping capabilities, or
823  * whatever), and you want to make sure that seeding happens before your
824  * program loses the ability to do it.
825  */
826 EVENT2_EXPORT_SYMBOL
827 int evutil_secure_rng_init(void);
828 
829 /**
830  * Set a filename to use in place of /dev/urandom for seeding the secure
831  * PRNG. Return 0 on success, -1 on failure.
832  *
833  * Call this function BEFORE calling any other initialization or RNG
834  * functions.
835  *
836  * (This string will _NOT_ be copied internally. Do not free it while any
837  * user of the secure RNG might be running. Don't pass anything other than a
838  * real /dev/...random device file here, or you might lose security.)
839  *
840  * This API is unstable, and might change in a future libevent version.
841  */
842 EVENT2_EXPORT_SYMBOL
843 int evutil_secure_rng_set_urandom_device_file(char *fname);
844 
845 /** Seed the random number generator with extra random bytes.
846 
847     You should almost never need to call this function; it should be
848     sufficient to invoke evutil_secure_rng_init(), or let Libevent take
849     care of calling evutil_secure_rng_init() on its own.
850 
851     If you call this function as a _replacement_ for the regular
852     entropy sources, then you need to be sure that your input
853     contains a fairly large amount of strong entropy.  Doing so is
854     notoriously hard: most people who try get it wrong.  Watch out!
855 
856     @param dat a buffer full of a strong source of random numbers
857     @param datlen the number of bytes to read from datlen
858  */
859 EVENT2_EXPORT_SYMBOL
860 void evutil_secure_rng_add_bytes(const char *dat, size_t datlen);
861 
862 #ifdef __cplusplus
863 }
864 #endif
865 
866 #endif /* EVENT1_EVUTIL_H_INCLUDED_ */
867