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