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