1290001Sglebius/* 2290001Sglebius * Copyright (c) 2007-2012 Niels Provos and Nick Mathewson 3290001Sglebius * 4290001Sglebius * Redistribution and use in source and binary forms, with or without 5290001Sglebius * modification, are permitted provided that the following conditions 6290001Sglebius * are met: 7290001Sglebius * 1. Redistributions of source code must retain the above copyright 8290001Sglebius * notice, this list of conditions and the following disclaimer. 9290001Sglebius * 2. Redistributions in binary form must reproduce the above copyright 10290001Sglebius * notice, this list of conditions and the following disclaimer in the 11290001Sglebius * documentation and/or other materials provided with the distribution. 12290001Sglebius * 3. The name of the author may not be used to endorse or promote products 13290001Sglebius * derived from this software without specific prior written permission. 14290001Sglebius * 15290001Sglebius * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16290001Sglebius * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17290001Sglebius * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18290001Sglebius * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19290001Sglebius * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20290001Sglebius * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21290001Sglebius * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22290001Sglebius * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23290001Sglebius * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24290001Sglebius * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25290001Sglebius */ 26290001Sglebius#ifndef EVENT2_UTIL_H_INCLUDED_ 27290001Sglebius#define EVENT2_UTIL_H_INCLUDED_ 28290001Sglebius 29290001Sglebius/** @file event2/util.h 30290001Sglebius 31290001Sglebius Common convenience functions for cross-platform portability and 32290001Sglebius related socket manipulations. 33290001Sglebius 34290001Sglebius */ 35290001Sglebius#include <event2/visibility.h> 36290001Sglebius 37290001Sglebius#ifdef __cplusplus 38290001Sglebiusextern "C" { 39290001Sglebius#endif 40290001Sglebius 41290001Sglebius#include <event2/event-config.h> 42290001Sglebius#ifdef EVENT__HAVE_SYS_TIME_H 43290001Sglebius#include <sys/time.h> 44290001Sglebius#endif 45290001Sglebius#ifdef EVENT__HAVE_STDINT_H 46290001Sglebius#include <stdint.h> 47290001Sglebius#elif defined(EVENT__HAVE_INTTYPES_H) 48290001Sglebius#include <inttypes.h> 49290001Sglebius#endif 50290001Sglebius#ifdef EVENT__HAVE_SYS_TYPES_H 51290001Sglebius#include <sys/types.h> 52290001Sglebius#endif 53290001Sglebius#ifdef EVENT__HAVE_STDDEF_H 54290001Sglebius#include <stddef.h> 55290001Sglebius#endif 56290001Sglebius#ifdef _MSC_VER 57290001Sglebius#include <BaseTsd.h> 58290001Sglebius#endif 59290001Sglebius#include <stdarg.h> 60290001Sglebius#ifdef EVENT__HAVE_NETDB_H 61290001Sglebius#if !defined(_GNU_SOURCE) 62290001Sglebius#define _GNU_SOURCE 63290001Sglebius#endif 64290001Sglebius#include <netdb.h> 65290001Sglebius#endif 66290001Sglebius 67290001Sglebius#ifdef _WIN32 68290001Sglebius#include <winsock2.h> 69290001Sglebius#ifdef EVENT__HAVE_GETADDRINFO 70290001Sglebius/* for EAI_* definitions. */ 71290001Sglebius#include <ws2tcpip.h> 72290001Sglebius#endif 73290001Sglebius#else 74290001Sglebius#include <sys/socket.h> 75290001Sglebius#endif 76290001Sglebius 77290001Sglebius/* Some openbsd autoconf versions get the name of this macro wrong. */ 78290001Sglebius#if defined(EVENT__SIZEOF_VOID__) && !defined(EVENT__SIZEOF_VOID_P) 79290001Sglebius#define EVENT__SIZEOF_VOID_P EVENT__SIZEOF_VOID__ 80290001Sglebius#endif 81290001Sglebius 82290001Sglebius/** 83290001Sglebius * @name Standard integer types. 84290001Sglebius * 85290001Sglebius * Integer type definitions for types that are supposed to be defined in the 86290001Sglebius * C99-specified stdint.h. Shamefully, some platforms do not include 87290001Sglebius * stdint.h, so we need to replace it. (If you are on a platform like this, 88290001Sglebius * your C headers are now over 10 years out of date. You should bug them to 89290001Sglebius * do something about this.) 90290001Sglebius * 91290001Sglebius * We define: 92290001Sglebius * 93290001Sglebius * <dl> 94290001Sglebius * <dt>ev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t</dt> 95290001Sglebius * <dd>unsigned integer types of exactly 64, 32, 16, and 8 bits 96290001Sglebius * respectively.</dd> 97290001Sglebius * <dt>ev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t</dt> 98290001Sglebius * <dd>signed integer types of exactly 64, 32, 16, and 8 bits 99290001Sglebius * respectively.</dd> 100290001Sglebius * <dt>ev_uintptr_t, ev_intptr_t</dt> 101290001Sglebius * <dd>unsigned/signed integers large enough 102290001Sglebius * to hold a pointer without loss of bits.</dd> 103290001Sglebius * <dt>ev_ssize_t</dt> 104290001Sglebius * <dd>A signed type of the same size as size_t</dd> 105290001Sglebius * <dt>ev_off_t</dt> 106290001Sglebius * <dd>A signed type typically used to represent offsets within a 107290001Sglebius * (potentially large) file</dd> 108290001Sglebius * 109290001Sglebius * @{ 110290001Sglebius */ 111290001Sglebius#ifdef EVENT__HAVE_UINT64_T 112290001Sglebius#define ev_uint64_t uint64_t 113290001Sglebius#define ev_int64_t int64_t 114290001Sglebius#elif defined(_WIN32) 115290001Sglebius#define ev_uint64_t unsigned __int64 116290001Sglebius#define ev_int64_t signed __int64 117290001Sglebius#elif EVENT__SIZEOF_LONG_LONG == 8 118290001Sglebius#define ev_uint64_t unsigned long long 119290001Sglebius#define ev_int64_t long long 120290001Sglebius#elif EVENT__SIZEOF_LONG == 8 121290001Sglebius#define ev_uint64_t unsigned long 122290001Sglebius#define ev_int64_t long 123290001Sglebius#elif defined(EVENT_IN_DOXYGEN_) 124290001Sglebius#define ev_uint64_t ... 125290001Sglebius#define ev_int64_t ... 126290001Sglebius#else 127290001Sglebius#error "No way to define ev_uint64_t" 128290001Sglebius#endif 129290001Sglebius 130290001Sglebius#ifdef EVENT__HAVE_UINT32_T 131290001Sglebius#define ev_uint32_t uint32_t 132290001Sglebius#define ev_int32_t int32_t 133290001Sglebius#elif defined(_WIN32) 134290001Sglebius#define ev_uint32_t unsigned int 135290001Sglebius#define ev_int32_t signed int 136290001Sglebius#elif EVENT__SIZEOF_LONG == 4 137290001Sglebius#define ev_uint32_t unsigned long 138290001Sglebius#define ev_int32_t signed long 139290001Sglebius#elif EVENT__SIZEOF_INT == 4 140290001Sglebius#define ev_uint32_t unsigned int 141290001Sglebius#define ev_int32_t signed int 142290001Sglebius#elif defined(EVENT_IN_DOXYGEN_) 143290001Sglebius#define ev_uint32_t ... 144290001Sglebius#define ev_int32_t ... 145290001Sglebius#else 146290001Sglebius#error "No way to define ev_uint32_t" 147290001Sglebius#endif 148290001Sglebius 149290001Sglebius#ifdef EVENT__HAVE_UINT16_T 150290001Sglebius#define ev_uint16_t uint16_t 151290001Sglebius#define ev_int16_t int16_t 152290001Sglebius#elif defined(_WIN32) 153290001Sglebius#define ev_uint16_t unsigned short 154290001Sglebius#define ev_int16_t signed short 155290001Sglebius#elif EVENT__SIZEOF_INT == 2 156290001Sglebius#define ev_uint16_t unsigned int 157290001Sglebius#define ev_int16_t signed int 158290001Sglebius#elif EVENT__SIZEOF_SHORT == 2 159290001Sglebius#define ev_uint16_t unsigned short 160290001Sglebius#define ev_int16_t signed short 161290001Sglebius#elif defined(EVENT_IN_DOXYGEN_) 162290001Sglebius#define ev_uint16_t ... 163290001Sglebius#define ev_int16_t ... 164290001Sglebius#else 165290001Sglebius#error "No way to define ev_uint16_t" 166290001Sglebius#endif 167290001Sglebius 168290001Sglebius#ifdef EVENT__HAVE_UINT8_T 169290001Sglebius#define ev_uint8_t uint8_t 170290001Sglebius#define ev_int8_t int8_t 171290001Sglebius#elif defined(EVENT_IN_DOXYGEN_) 172290001Sglebius#define ev_uint8_t ... 173290001Sglebius#define ev_int8_t ... 174290001Sglebius#else 175290001Sglebius#define ev_uint8_t unsigned char 176290001Sglebius#define ev_int8_t signed char 177290001Sglebius#endif 178290001Sglebius 179290001Sglebius#ifdef EVENT__HAVE_UINTPTR_T 180290001Sglebius#define ev_uintptr_t uintptr_t 181290001Sglebius#define ev_intptr_t intptr_t 182290001Sglebius#elif EVENT__SIZEOF_VOID_P <= 4 183290001Sglebius#define ev_uintptr_t ev_uint32_t 184290001Sglebius#define ev_intptr_t ev_int32_t 185290001Sglebius#elif EVENT__SIZEOF_VOID_P <= 8 186290001Sglebius#define ev_uintptr_t ev_uint64_t 187290001Sglebius#define ev_intptr_t ev_int64_t 188290001Sglebius#elif defined(EVENT_IN_DOXYGEN_) 189290001Sglebius#define ev_uintptr_t ... 190290001Sglebius#define ev_intptr_t ... 191290001Sglebius#else 192290001Sglebius#error "No way to define ev_uintptr_t" 193290001Sglebius#endif 194290001Sglebius 195290001Sglebius#ifdef EVENT__ssize_t 196290001Sglebius#define ev_ssize_t EVENT__ssize_t 197290001Sglebius#else 198290001Sglebius#define ev_ssize_t ssize_t 199290001Sglebius#endif 200290001Sglebius 201290001Sglebius/* Note that we define ev_off_t based on the compile-time size of off_t that 202290001Sglebius * we used to build Libevent, and not based on the current size of off_t. 203290001Sglebius * (For example, we don't define ev_off_t to off_t.). We do this because 204290001Sglebius * some systems let you build your software with different off_t sizes 205290001Sglebius * at runtime, and so putting in any dependency on off_t would risk API 206290001Sglebius * mismatch. 207290001Sglebius */ 208290001Sglebius#ifdef _WIN32 209290001Sglebius#define ev_off_t ev_int64_t 210290001Sglebius#elif EVENT__SIZEOF_OFF_T == 8 211290001Sglebius#define ev_off_t ev_int64_t 212290001Sglebius#elif EVENT__SIZEOF_OFF_T == 4 213290001Sglebius#define ev_off_t ev_int32_t 214290001Sglebius#elif defined(EVENT_IN_DOXYGEN_) 215290001Sglebius#define ev_off_t ... 216290001Sglebius#else 217290001Sglebius#define ev_off_t off_t 218290001Sglebius#endif 219290001Sglebius/**@}*/ 220290001Sglebius 221290001Sglebius/* Limits for integer types. 222290001Sglebius 223290001Sglebius We're making two assumptions here: 224290001Sglebius - The compiler does constant folding properly. 225290001Sglebius - The platform does signed arithmetic in two's complement. 226290001Sglebius*/ 227290001Sglebius 228290001Sglebius/** 229290001Sglebius @name Limits for integer types 230290001Sglebius 231290001Sglebius These macros hold the largest or smallest values possible for the 232290001Sglebius ev_[u]int*_t types. 233290001Sglebius 234290001Sglebius @{ 235290001Sglebius*/ 236290001Sglebius#define EV_UINT64_MAX ((((ev_uint64_t)0xffffffffUL) << 32) | 0xffffffffUL) 237290001Sglebius#define EV_INT64_MAX ((((ev_int64_t) 0x7fffffffL) << 32) | 0xffffffffL) 238290001Sglebius#define EV_INT64_MIN ((-EV_INT64_MAX) - 1) 239290001Sglebius#define EV_UINT32_MAX ((ev_uint32_t)0xffffffffUL) 240290001Sglebius#define EV_INT32_MAX ((ev_int32_t) 0x7fffffffL) 241290001Sglebius#define EV_INT32_MIN ((-EV_INT32_MAX) - 1) 242290001Sglebius#define EV_UINT16_MAX ((ev_uint16_t)0xffffUL) 243290001Sglebius#define EV_INT16_MAX ((ev_int16_t) 0x7fffL) 244290001Sglebius#define EV_INT16_MIN ((-EV_INT16_MAX) - 1) 245290001Sglebius#define EV_UINT8_MAX 255 246290001Sglebius#define EV_INT8_MAX 127 247290001Sglebius#define EV_INT8_MIN ((-EV_INT8_MAX) - 1) 248290001Sglebius/** @} */ 249290001Sglebius 250290001Sglebius/** 251290001Sglebius @name Limits for SIZE_T and SSIZE_T 252290001Sglebius 253290001Sglebius @{ 254290001Sglebius*/ 255290001Sglebius#if EVENT__SIZEOF_SIZE_T == 8 256290001Sglebius#define EV_SIZE_MAX EV_UINT64_MAX 257290001Sglebius#define EV_SSIZE_MAX EV_INT64_MAX 258290001Sglebius#elif EVENT__SIZEOF_SIZE_T == 4 259290001Sglebius#define EV_SIZE_MAX EV_UINT32_MAX 260290001Sglebius#define EV_SSIZE_MAX EV_INT32_MAX 261290001Sglebius#elif defined(EVENT_IN_DOXYGEN_) 262290001Sglebius#define EV_SIZE_MAX ... 263290001Sglebius#define EV_SSIZE_MAX ... 264290001Sglebius#else 265290001Sglebius#error "No way to define SIZE_MAX" 266290001Sglebius#endif 267290001Sglebius 268290001Sglebius#define EV_SSIZE_MIN ((-EV_SSIZE_MAX) - 1) 269290001Sglebius/**@}*/ 270290001Sglebius 271290001Sglebius#ifdef _WIN32 272290001Sglebius#define ev_socklen_t int 273290001Sglebius#elif defined(EVENT__socklen_t) 274290001Sglebius#define ev_socklen_t EVENT__socklen_t 275290001Sglebius#else 276290001Sglebius#define ev_socklen_t socklen_t 277290001Sglebius#endif 278290001Sglebius 279290001Sglebius#ifdef EVENT__HAVE_STRUCT_SOCKADDR_STORAGE___SS_FAMILY 280290001Sglebius#if !defined(EVENT__HAVE_STRUCT_SOCKADDR_STORAGE_SS_FAMILY) \ 281290001Sglebius && !defined(ss_family) 282290001Sglebius#define ss_family __ss_family 283290001Sglebius#endif 284290001Sglebius#endif 285290001Sglebius 286290001Sglebius/** 287290001Sglebius * A type wide enough to hold the output of "socket()" or "accept()". On 288290001Sglebius * Windows, this is an intptr_t; elsewhere, it is an int. */ 289290001Sglebius#ifdef _WIN32 290290001Sglebius#define evutil_socket_t intptr_t 291290001Sglebius#else 292290001Sglebius#define evutil_socket_t int 293290001Sglebius#endif 294290001Sglebius 295290001Sglebius/** 296290001Sglebius * Structure to hold information about a monotonic timer 297290001Sglebius * 298290001Sglebius * Use this with evutil_configure_monotonic_time() and 299290001Sglebius * evutil_gettime_monotonic(). 300290001Sglebius * 301290001Sglebius * This is an opaque structure; you can allocate one using 302290001Sglebius * evutil_monotonic_timer_new(). 303290001Sglebius * 304290001Sglebius * @see evutil_monotonic_timer_new(), evutil_monotonic_timer_free(), 305290001Sglebius * evutil_configure_monotonic_time(), evutil_gettime_monotonic() 306290001Sglebius */ 307290001Sglebiusstruct evutil_monotonic_timer 308290001Sglebius#ifdef EVENT_IN_DOXYGEN_ 309290001Sglebius{/*Empty body so that doxygen will generate documentation here.*/} 310290001Sglebius#endif 311290001Sglebius; 312290001Sglebius 313290001Sglebius#define EV_MONOT_PRECISE 1 314290001Sglebius#define EV_MONOT_FALLBACK 2 315290001Sglebius 316290001Sglebius/** Allocate a new struct evutil_monotonic_timer for use with the 317290001Sglebius * evutil_configure_monotonic_time() and evutil_gettime_monotonic() 318290001Sglebius * functions. You must configure the timer with 319290001Sglebius * evutil_configure_monotonic_time() before using it. 320290001Sglebius */ 321290001SglebiusEVENT2_EXPORT_SYMBOL 322290001Sglebiusstruct evutil_monotonic_timer * evutil_monotonic_timer_new(void); 323290001Sglebius 324290001Sglebius/** Free a struct evutil_monotonic_timer that was allocated using 325290001Sglebius * evutil_monotonic_timer_new(). 326290001Sglebius */ 327290001SglebiusEVENT2_EXPORT_SYMBOL 328290001Sglebiusvoid evutil_monotonic_timer_free(struct evutil_monotonic_timer *timer); 329290001Sglebius 330290001Sglebius/** Set up a struct evutil_monotonic_timer; flags can include 331290001Sglebius * EV_MONOT_PRECISE and EV_MONOT_FALLBACK. 332290001Sglebius */ 333290001SglebiusEVENT2_EXPORT_SYMBOL 334290001Sglebiusint evutil_configure_monotonic_time(struct evutil_monotonic_timer *timer, 335290001Sglebius int flags); 336290001Sglebius 337290001Sglebius/** Query the current monotonic time from a struct evutil_monotonic_timer 338290001Sglebius * previously configured with evutil_configure_monotonic_time(). Monotonic 339290001Sglebius * time is guaranteed never to run in reverse, but is not necessarily epoch- 340290001Sglebius * based, or relative to any other definite point. Use it to make reliable 341290001Sglebius * measurements of elapsed time between events even when the system time 342290001Sglebius * may be changed. 343290001Sglebius * 344290001Sglebius * It is not safe to use this funtion on the same timer from multiple 345290001Sglebius * threads. 346290001Sglebius */ 347290001SglebiusEVENT2_EXPORT_SYMBOL 348290001Sglebiusint evutil_gettime_monotonic(struct evutil_monotonic_timer *timer, 349290001Sglebius struct timeval *tp); 350290001Sglebius 351290001Sglebius/** Create two new sockets that are connected to each other. 352290001Sglebius 353290001Sglebius On Unix, this simply calls socketpair(). On Windows, it uses the 354290001Sglebius loopback network interface on 127.0.0.1, and only 355290001Sglebius AF_INET,SOCK_STREAM are supported. 356290001Sglebius 357290001Sglebius (This may fail on some Windows hosts where firewall software has cleverly 358290001Sglebius decided to keep 127.0.0.1 from talking to itself.) 359290001Sglebius 360290001Sglebius Parameters and return values are as for socketpair() 361290001Sglebius*/ 362290001SglebiusEVENT2_EXPORT_SYMBOL 363290001Sglebiusint evutil_socketpair(int d, int type, int protocol, evutil_socket_t sv[2]); 364290001Sglebius/** Do platform-specific operations as needed to make a socket nonblocking. 365290001Sglebius 366290001Sglebius @param sock The socket to make nonblocking 367290001Sglebius @return 0 on success, -1 on failure 368290001Sglebius */ 369290001SglebiusEVENT2_EXPORT_SYMBOL 370290001Sglebiusint evutil_make_socket_nonblocking(evutil_socket_t sock); 371290001Sglebius 372290001Sglebius/** Do platform-specific operations to make a listener socket reusable. 373290001Sglebius 374290001Sglebius Specifically, we want to make sure that another program will be able 375290001Sglebius to bind this address right after we've closed the listener. 376290001Sglebius 377290001Sglebius This differs from Windows's interpretation of "reusable", which 378290001Sglebius allows multiple listeners to bind the same address at the same time. 379290001Sglebius 380290001Sglebius @param sock The socket to make reusable 381290001Sglebius @return 0 on success, -1 on failure 382290001Sglebius */ 383290001SglebiusEVENT2_EXPORT_SYMBOL 384290001Sglebiusint evutil_make_listen_socket_reuseable(evutil_socket_t sock); 385290001Sglebius 386290001Sglebius/** Do platform-specific operations to make a listener port reusable. 387290001Sglebius 388290001Sglebius Specifically, we want to make sure that multiple programs which also 389290001Sglebius set the same socket option will be able to bind, listen at the same time. 390290001Sglebius 391290001Sglebius This is a feature available only to Linux 3.9+ 392290001Sglebius 393290001Sglebius @param sock The socket to make reusable 394290001Sglebius @return 0 on success, -1 on failure 395290001Sglebius */ 396290001SglebiusEVENT2_EXPORT_SYMBOL 397290001Sglebiusint evutil_make_listen_socket_reuseable_port(evutil_socket_t sock); 398290001Sglebius 399290001Sglebius/** Do platform-specific operations as needed to close a socket upon a 400290001Sglebius successful execution of one of the exec*() functions. 401290001Sglebius 402290001Sglebius @param sock The socket to be closed 403290001Sglebius @return 0 on success, -1 on failure 404290001Sglebius */ 405290001SglebiusEVENT2_EXPORT_SYMBOL 406290001Sglebiusint evutil_make_socket_closeonexec(evutil_socket_t sock); 407290001Sglebius 408290001Sglebius/** Do the platform-specific call needed to close a socket returned from 409290001Sglebius socket() or accept(). 410290001Sglebius 411290001Sglebius @param sock The socket to be closed 412290001Sglebius @return 0 on success, -1 on failure 413290001Sglebius */ 414290001SglebiusEVENT2_EXPORT_SYMBOL 415290001Sglebiusint evutil_closesocket(evutil_socket_t sock); 416290001Sglebius#define EVUTIL_CLOSESOCKET(s) evutil_closesocket(s) 417290001Sglebius 418290001Sglebius/** Do platform-specific operations, if possible, to make a tcp listener 419290001Sglebius * socket defer accept()s until there is data to read. 420290001Sglebius * 421290001Sglebius * Not all platforms support this. You don't want to do this for every 422290001Sglebius * listener socket: only the ones that implement a protocol where the 423290001Sglebius * client transmits before the server needs to respond. 424290001Sglebius * 425290001Sglebius * @param sock The listening socket to to make deferred 426290001Sglebius * @return 0 on success (whether the operation is supported or not), 427290001Sglebius * -1 on failure 428290001Sglebius*/ 429290001SglebiusEVENT2_EXPORT_SYMBOL 430290001Sglebiusint evutil_make_tcp_listen_socket_deferred(evutil_socket_t sock); 431290001Sglebius 432290001Sglebius#ifdef _WIN32 433290001Sglebius/** Return the most recent socket error. Not idempotent on all platforms. */ 434290001Sglebius#define EVUTIL_SOCKET_ERROR() WSAGetLastError() 435290001Sglebius/** Replace the most recent socket error with errcode */ 436290001Sglebius#define EVUTIL_SET_SOCKET_ERROR(errcode) \ 437290001Sglebius do { WSASetLastError(errcode); } while (0) 438290001Sglebius/** Return the most recent socket error to occur on sock. */ 439290001SglebiusEVENT2_EXPORT_SYMBOL 440290001Sglebiusint evutil_socket_geterror(evutil_socket_t sock); 441290001Sglebius/** Convert a socket error to a string. */ 442290001SglebiusEVENT2_EXPORT_SYMBOL 443290001Sglebiusconst char *evutil_socket_error_to_string(int errcode); 444290001Sglebius#elif defined(EVENT_IN_DOXYGEN_) 445290001Sglebius/** 446290001Sglebius @name Socket error functions 447290001Sglebius 448290001Sglebius These functions are needed for making programs compatible between 449290001Sglebius Windows and Unix-like platforms. 450290001Sglebius 451290001Sglebius You see, Winsock handles socket errors differently from the rest of 452290001Sglebius the world. Elsewhere, a socket error is like any other error and is 453290001Sglebius stored in errno. But winsock functions require you to retrieve the 454290001Sglebius error with a special function, and don't let you use strerror for 455290001Sglebius the error codes. And handling EWOULDBLOCK is ... different. 456290001Sglebius 457290001Sglebius @{ 458290001Sglebius*/ 459290001Sglebius/** Return the most recent socket error. Not idempotent on all platforms. */ 460290001Sglebius#define EVUTIL_SOCKET_ERROR() ... 461290001Sglebius/** Replace the most recent socket error with errcode */ 462290001Sglebius#define EVUTIL_SET_SOCKET_ERROR(errcode) ... 463290001Sglebius/** Return the most recent socket error to occur on sock. */ 464290001Sglebius#define evutil_socket_geterror(sock) ... 465290001Sglebius/** Convert a socket error to a string. */ 466290001Sglebius#define evutil_socket_error_to_string(errcode) ... 467290001Sglebius/**@}*/ 468290001Sglebius#else 469290001Sglebius#define EVUTIL_SOCKET_ERROR() (errno) 470290001Sglebius#define EVUTIL_SET_SOCKET_ERROR(errcode) \ 471290001Sglebius do { errno = (errcode); } while (0) 472290001Sglebius#define evutil_socket_geterror(sock) (errno) 473290001Sglebius#define evutil_socket_error_to_string(errcode) (strerror(errcode)) 474290001Sglebius#endif 475290001Sglebius 476290001Sglebius 477290001Sglebius/** 478290001Sglebius * @name Manipulation macros for struct timeval. 479290001Sglebius * 480290001Sglebius * We define replacements 481290001Sglebius * for timeradd, timersub, timerclear, timercmp, and timerisset. 482290001Sglebius * 483290001Sglebius * @{ 484290001Sglebius */ 485290001Sglebius#ifdef EVENT__HAVE_TIMERADD 486290001Sglebius#define evutil_timeradd(tvp, uvp, vvp) timeradd((tvp), (uvp), (vvp)) 487290001Sglebius#define evutil_timersub(tvp, uvp, vvp) timersub((tvp), (uvp), (vvp)) 488290001Sglebius#else 489290001Sglebius#define evutil_timeradd(tvp, uvp, vvp) \ 490290001Sglebius do { \ 491290001Sglebius (vvp)->tv_sec = (tvp)->tv_sec + (uvp)->tv_sec; \ 492290001Sglebius (vvp)->tv_usec = (tvp)->tv_usec + (uvp)->tv_usec; \ 493290001Sglebius if ((vvp)->tv_usec >= 1000000) { \ 494290001Sglebius (vvp)->tv_sec++; \ 495290001Sglebius (vvp)->tv_usec -= 1000000; \ 496290001Sglebius } \ 497290001Sglebius } while (0) 498290001Sglebius#define evutil_timersub(tvp, uvp, vvp) \ 499290001Sglebius do { \ 500290001Sglebius (vvp)->tv_sec = (tvp)->tv_sec - (uvp)->tv_sec; \ 501290001Sglebius (vvp)->tv_usec = (tvp)->tv_usec - (uvp)->tv_usec; \ 502290001Sglebius if ((vvp)->tv_usec < 0) { \ 503290001Sglebius (vvp)->tv_sec--; \ 504290001Sglebius (vvp)->tv_usec += 1000000; \ 505290001Sglebius } \ 506290001Sglebius } while (0) 507290001Sglebius#endif /* !EVENT__HAVE_TIMERADD */ 508290001Sglebius 509290001Sglebius#ifdef EVENT__HAVE_TIMERCLEAR 510290001Sglebius#define evutil_timerclear(tvp) timerclear(tvp) 511290001Sglebius#else 512290001Sglebius#define evutil_timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0 513290001Sglebius#endif 514290001Sglebius/**@}*/ 515290001Sglebius 516290001Sglebius/** Return true iff the tvp is related to uvp according to the relational 517290001Sglebius * operator cmp. Recognized values for cmp are ==, <=, <, >=, and >. */ 518290001Sglebius#define evutil_timercmp(tvp, uvp, cmp) \ 519290001Sglebius (((tvp)->tv_sec == (uvp)->tv_sec) ? \ 520290001Sglebius ((tvp)->tv_usec cmp (uvp)->tv_usec) : \ 521290001Sglebius ((tvp)->tv_sec cmp (uvp)->tv_sec)) 522290001Sglebius 523290001Sglebius#ifdef EVENT__HAVE_TIMERISSET 524290001Sglebius#define evutil_timerisset(tvp) timerisset(tvp) 525290001Sglebius#else 526290001Sglebius#define evutil_timerisset(tvp) ((tvp)->tv_sec || (tvp)->tv_usec) 527290001Sglebius#endif 528290001Sglebius 529290001Sglebius/** Replacement for offsetof on platforms that don't define it. */ 530290001Sglebius#ifdef offsetof 531290001Sglebius#define evutil_offsetof(type, field) offsetof(type, field) 532290001Sglebius#else 533290001Sglebius#define evutil_offsetof(type, field) ((off_t)(&((type *)0)->field)) 534290001Sglebius#endif 535290001Sglebius 536290001Sglebius/* big-int related functions */ 537290001Sglebius/** Parse a 64-bit value from a string. Arguments are as for strtol. */ 538290001SglebiusEVENT2_EXPORT_SYMBOL 539290001Sglebiusev_int64_t evutil_strtoll(const char *s, char **endptr, int base); 540290001Sglebius 541290001Sglebius/** Replacement for gettimeofday on platforms that lack it. */ 542290001Sglebius#ifdef EVENT__HAVE_GETTIMEOFDAY 543290001Sglebius#define evutil_gettimeofday(tv, tz) gettimeofday((tv), (tz)) 544290001Sglebius#else 545290001Sglebiusstruct timezone; 546290001SglebiusEVENT2_EXPORT_SYMBOL 547290001Sglebiusint evutil_gettimeofday(struct timeval *tv, struct timezone *tz); 548290001Sglebius#endif 549290001Sglebius 550290001Sglebius/** Replacement for snprintf to get consistent behavior on platforms for 551290001Sglebius which the return value of snprintf does not conform to C99. 552290001Sglebius */ 553290001SglebiusEVENT2_EXPORT_SYMBOL 554290001Sglebiusint evutil_snprintf(char *buf, size_t buflen, const char *format, ...) 555290001Sglebius#ifdef __GNUC__ 556290001Sglebius __attribute__((format(printf, 3, 4))) 557290001Sglebius#endif 558290001Sglebius; 559290001Sglebius/** Replacement for vsnprintf to get consistent behavior on platforms for 560290001Sglebius which the return value of snprintf does not conform to C99. 561290001Sglebius */ 562290001SglebiusEVENT2_EXPORT_SYMBOL 563290001Sglebiusint evutil_vsnprintf(char *buf, size_t buflen, const char *format, va_list ap) 564290001Sglebius#ifdef __GNUC__ 565290001Sglebius __attribute__((format(printf, 3, 0))) 566290001Sglebius#endif 567290001Sglebius; 568290001Sglebius 569290001Sglebius/** Replacement for inet_ntop for platforms which lack it. */ 570290001SglebiusEVENT2_EXPORT_SYMBOL 571290001Sglebiusconst char *evutil_inet_ntop(int af, const void *src, char *dst, size_t len); 572290001Sglebius/** Replacement for inet_pton for platforms which lack it. */ 573290001SglebiusEVENT2_EXPORT_SYMBOL 574290001Sglebiusint evutil_inet_pton(int af, const char *src, void *dst); 575290001Sglebiusstruct sockaddr; 576290001Sglebius 577290001Sglebius/** Parse an IPv4 or IPv6 address, with optional port, from a string. 578290001Sglebius 579290001Sglebius Recognized formats are: 580290001Sglebius - [IPv6Address]:port 581290001Sglebius - [IPv6Address] 582290001Sglebius - IPv6Address 583290001Sglebius - IPv4Address:port 584290001Sglebius - IPv4Address 585290001Sglebius 586290001Sglebius If no port is specified, the port in the output is set to 0. 587290001Sglebius 588290001Sglebius @param str The string to parse. 589290001Sglebius @param out A struct sockaddr to hold the result. This should probably be 590290001Sglebius a struct sockaddr_storage. 591290001Sglebius @param outlen A pointer to the number of bytes that that 'out' can safely 592290001Sglebius hold. Set to the number of bytes used in 'out' on success. 593290001Sglebius @return -1 if the address is not well-formed, if the port is out of range, 594290001Sglebius or if out is not large enough to hold the result. Otherwise returns 595290001Sglebius 0 on success. 596290001Sglebius*/ 597290001SglebiusEVENT2_EXPORT_SYMBOL 598290001Sglebiusint evutil_parse_sockaddr_port(const char *str, struct sockaddr *out, int *outlen); 599290001Sglebius 600290001Sglebius/** Compare two sockaddrs; return 0 if they are equal, or less than 0 if sa1 601290001Sglebius * preceeds sa2, or greater than 0 if sa1 follows sa2. If include_port is 602290001Sglebius * true, consider the port as well as the address. Only implemented for 603290001Sglebius * AF_INET and AF_INET6 addresses. The ordering is not guaranteed to remain 604290001Sglebius * the same between Libevent versions. */ 605290001SglebiusEVENT2_EXPORT_SYMBOL 606290001Sglebiusint evutil_sockaddr_cmp(const struct sockaddr *sa1, const struct sockaddr *sa2, 607290001Sglebius int include_port); 608290001Sglebius 609290001Sglebius/** As strcasecmp, but always compares the characters in locale-independent 610290001Sglebius ASCII. That's useful if you're handling data in ASCII-based protocols. 611290001Sglebius */ 612290001SglebiusEVENT2_EXPORT_SYMBOL 613290001Sglebiusint evutil_ascii_strcasecmp(const char *str1, const char *str2); 614290001Sglebius/** As strncasecmp, but always compares the characters in locale-independent 615290001Sglebius ASCII. That's useful if you're handling data in ASCII-based protocols. 616290001Sglebius */ 617290001SglebiusEVENT2_EXPORT_SYMBOL 618290001Sglebiusint evutil_ascii_strncasecmp(const char *str1, const char *str2, size_t n); 619290001Sglebius 620290001Sglebius/* Here we define evutil_addrinfo to the native addrinfo type, or redefine it 621290001Sglebius * if this system has no getaddrinfo(). */ 622290001Sglebius#ifdef EVENT__HAVE_STRUCT_ADDRINFO 623290001Sglebius#define evutil_addrinfo addrinfo 624290001Sglebius#else 625290001Sglebius/** A definition of struct addrinfo for systems that lack it. 626290001Sglebius 627290001Sglebius (This is just an alias for struct addrinfo if the system defines 628290001Sglebius struct addrinfo.) 629290001Sglebius*/ 630290001Sglebiusstruct evutil_addrinfo { 631290001Sglebius int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */ 632290001Sglebius int ai_family; /* PF_xxx */ 633290001Sglebius int ai_socktype; /* SOCK_xxx */ 634290001Sglebius int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ 635290001Sglebius size_t ai_addrlen; /* length of ai_addr */ 636290001Sglebius char *ai_canonname; /* canonical name for nodename */ 637290001Sglebius struct sockaddr *ai_addr; /* binary address */ 638290001Sglebius struct evutil_addrinfo *ai_next; /* next structure in linked list */ 639290001Sglebius}; 640290001Sglebius#endif 641290001Sglebius/** @name evutil_getaddrinfo() error codes 642290001Sglebius 643290001Sglebius These values are possible error codes for evutil_getaddrinfo() and 644290001Sglebius related functions. 645290001Sglebius 646290001Sglebius @{ 647290001Sglebius*/ 648290001Sglebius#if defined(EAI_ADDRFAMILY) && defined(EVENT__HAVE_GETADDRINFO) 649290001Sglebius#define EVUTIL_EAI_ADDRFAMILY EAI_ADDRFAMILY 650290001Sglebius#else 651290001Sglebius#define EVUTIL_EAI_ADDRFAMILY -901 652290001Sglebius#endif 653290001Sglebius#if defined(EAI_AGAIN) && defined(EVENT__HAVE_GETADDRINFO) 654290001Sglebius#define EVUTIL_EAI_AGAIN EAI_AGAIN 655290001Sglebius#else 656290001Sglebius#define EVUTIL_EAI_AGAIN -902 657290001Sglebius#endif 658290001Sglebius#if defined(EAI_BADFLAGS) && defined(EVENT__HAVE_GETADDRINFO) 659290001Sglebius#define EVUTIL_EAI_BADFLAGS EAI_BADFLAGS 660290001Sglebius#else 661290001Sglebius#define EVUTIL_EAI_BADFLAGS -903 662290001Sglebius#endif 663290001Sglebius#if defined(EAI_FAIL) && defined(EVENT__HAVE_GETADDRINFO) 664290001Sglebius#define EVUTIL_EAI_FAIL EAI_FAIL 665290001Sglebius#else 666290001Sglebius#define EVUTIL_EAI_FAIL -904 667290001Sglebius#endif 668290001Sglebius#if defined(EAI_FAMILY) && defined(EVENT__HAVE_GETADDRINFO) 669290001Sglebius#define EVUTIL_EAI_FAMILY EAI_FAMILY 670290001Sglebius#else 671290001Sglebius#define EVUTIL_EAI_FAMILY -905 672290001Sglebius#endif 673290001Sglebius#if defined(EAI_MEMORY) && defined(EVENT__HAVE_GETADDRINFO) 674290001Sglebius#define EVUTIL_EAI_MEMORY EAI_MEMORY 675290001Sglebius#else 676290001Sglebius#define EVUTIL_EAI_MEMORY -906 677290001Sglebius#endif 678290001Sglebius/* This test is a bit complicated, since some MS SDKs decide to 679290001Sglebius * remove NODATA or redefine it to be the same as NONAME, in a 680290001Sglebius * fun interpretation of RFC 2553 and RFC 3493. */ 681290001Sglebius#if defined(EAI_NODATA) && defined(EVENT__HAVE_GETADDRINFO) && (!defined(EAI_NONAME) || EAI_NODATA != EAI_NONAME) 682290001Sglebius#define EVUTIL_EAI_NODATA EAI_NODATA 683290001Sglebius#else 684290001Sglebius#define EVUTIL_EAI_NODATA -907 685290001Sglebius#endif 686290001Sglebius#if defined(EAI_NONAME) && defined(EVENT__HAVE_GETADDRINFO) 687290001Sglebius#define EVUTIL_EAI_NONAME EAI_NONAME 688290001Sglebius#else 689290001Sglebius#define EVUTIL_EAI_NONAME -908 690290001Sglebius#endif 691290001Sglebius#if defined(EAI_SERVICE) && defined(EVENT__HAVE_GETADDRINFO) 692290001Sglebius#define EVUTIL_EAI_SERVICE EAI_SERVICE 693290001Sglebius#else 694290001Sglebius#define EVUTIL_EAI_SERVICE -909 695290001Sglebius#endif 696290001Sglebius#if defined(EAI_SOCKTYPE) && defined(EVENT__HAVE_GETADDRINFO) 697290001Sglebius#define EVUTIL_EAI_SOCKTYPE EAI_SOCKTYPE 698290001Sglebius#else 699290001Sglebius#define EVUTIL_EAI_SOCKTYPE -910 700290001Sglebius#endif 701290001Sglebius#if defined(EAI_SYSTEM) && defined(EVENT__HAVE_GETADDRINFO) 702290001Sglebius#define EVUTIL_EAI_SYSTEM EAI_SYSTEM 703290001Sglebius#else 704290001Sglebius#define EVUTIL_EAI_SYSTEM -911 705290001Sglebius#endif 706290001Sglebius 707290001Sglebius#define EVUTIL_EAI_CANCEL -90001 708290001Sglebius 709290001Sglebius#if defined(AI_PASSIVE) && defined(EVENT__HAVE_GETADDRINFO) 710290001Sglebius#define EVUTIL_AI_PASSIVE AI_PASSIVE 711290001Sglebius#else 712290001Sglebius#define EVUTIL_AI_PASSIVE 0x1000 713290001Sglebius#endif 714290001Sglebius#if defined(AI_CANONNAME) && defined(EVENT__HAVE_GETADDRINFO) 715290001Sglebius#define EVUTIL_AI_CANONNAME AI_CANONNAME 716290001Sglebius#else 717290001Sglebius#define EVUTIL_AI_CANONNAME 0x2000 718290001Sglebius#endif 719290001Sglebius#if defined(AI_NUMERICHOST) && defined(EVENT__HAVE_GETADDRINFO) 720290001Sglebius#define EVUTIL_AI_NUMERICHOST AI_NUMERICHOST 721290001Sglebius#else 722290001Sglebius#define EVUTIL_AI_NUMERICHOST 0x4000 723290001Sglebius#endif 724290001Sglebius#if defined(AI_NUMERICSERV) && defined(EVENT__HAVE_GETADDRINFO) 725290001Sglebius#define EVUTIL_AI_NUMERICSERV AI_NUMERICSERV 726290001Sglebius#else 727290001Sglebius#define EVUTIL_AI_NUMERICSERV 0x8000 728290001Sglebius#endif 729290001Sglebius#if defined(AI_V4MAPPED) && defined(EVENT__HAVE_GETADDRINFO) 730290001Sglebius#define EVUTIL_AI_V4MAPPED AI_V4MAPPED 731290001Sglebius#else 732290001Sglebius#define EVUTIL_AI_V4MAPPED 0x10000 733290001Sglebius#endif 734290001Sglebius#if defined(AI_ALL) && defined(EVENT__HAVE_GETADDRINFO) 735290001Sglebius#define EVUTIL_AI_ALL AI_ALL 736290001Sglebius#else 737290001Sglebius#define EVUTIL_AI_ALL 0x20000 738290001Sglebius#endif 739290001Sglebius#if defined(AI_ADDRCONFIG) && defined(EVENT__HAVE_GETADDRINFO) 740290001Sglebius#define EVUTIL_AI_ADDRCONFIG AI_ADDRCONFIG 741290001Sglebius#else 742290001Sglebius#define EVUTIL_AI_ADDRCONFIG 0x40000 743290001Sglebius#endif 744290001Sglebius/**@}*/ 745290001Sglebius 746290001Sglebiusstruct evutil_addrinfo; 747290001Sglebius/** 748290001Sglebius * This function clones getaddrinfo for systems that don't have it. For full 749290001Sglebius * details, see RFC 3493, section 6.1. 750290001Sglebius * 751290001Sglebius * Limitations: 752290001Sglebius * - When the system has no getaddrinfo, we fall back to gethostbyname_r or 753290001Sglebius * gethostbyname, with their attendant issues. 754290001Sglebius * - The AI_V4MAPPED and AI_ALL flags are not currently implemented. 755290001Sglebius * 756290001Sglebius * For a nonblocking variant, see evdns_getaddrinfo. 757290001Sglebius */ 758290001SglebiusEVENT2_EXPORT_SYMBOL 759290001Sglebiusint evutil_getaddrinfo(const char *nodename, const char *servname, 760290001Sglebius const struct evutil_addrinfo *hints_in, struct evutil_addrinfo **res); 761290001Sglebius 762290001Sglebius/** Release storage allocated by evutil_getaddrinfo or evdns_getaddrinfo. */ 763290001SglebiusEVENT2_EXPORT_SYMBOL 764290001Sglebiusvoid evutil_freeaddrinfo(struct evutil_addrinfo *ai); 765290001Sglebius 766290001SglebiusEVENT2_EXPORT_SYMBOL 767290001Sglebiusconst char *evutil_gai_strerror(int err); 768290001Sglebius 769290001Sglebius/** Generate n bytes of secure pseudorandom data, and store them in buf. 770290001Sglebius * 771290001Sglebius * Current versions of Libevent use an ARC4-based random number generator, 772290001Sglebius * seeded using the platform's entropy source (/dev/urandom on Unix-like 773290001Sglebius * systems; CryptGenRandom on Windows). This is not actually as secure as it 774290001Sglebius * should be: ARC4 is a pretty lousy cipher, and the current implementation 775290001Sglebius * provides only rudimentary prediction- and backtracking-resistance. Don't 776290001Sglebius * use this for serious cryptographic applications. 777290001Sglebius */ 778290001SglebiusEVENT2_EXPORT_SYMBOL 779290001Sglebiusvoid evutil_secure_rng_get_bytes(void *buf, size_t n); 780290001Sglebius 781290001Sglebius/** 782290001Sglebius * Seed the secure random number generator if needed, and return 0 on 783290001Sglebius * success or -1 on failure. 784290001Sglebius * 785290001Sglebius * It is okay to call this function more than once; it will still return 786290001Sglebius * 0 if the RNG has been successfully seeded and -1 if it can't be 787290001Sglebius * seeded. 788290001Sglebius * 789290001Sglebius * Ordinarily you don't need to call this function from your own code; 790290001Sglebius * Libevent will seed the RNG itself the first time it needs good random 791290001Sglebius * numbers. You only need to call it if (a) you want to double-check 792290001Sglebius * that one of the seeding methods did succeed, or (b) you plan to drop 793290001Sglebius * the capability to seed (by chrooting, or dropping capabilities, or 794290001Sglebius * whatever), and you want to make sure that seeding happens before your 795290001Sglebius * program loses the ability to do it. 796290001Sglebius */ 797290001SglebiusEVENT2_EXPORT_SYMBOL 798290001Sglebiusint evutil_secure_rng_init(void); 799290001Sglebius 800290001Sglebius/** 801290001Sglebius * Set a filename to use in place of /dev/urandom for seeding the secure 802290001Sglebius * PRNG. Return 0 on success, -1 on failure. 803290001Sglebius * 804290001Sglebius * Call this function BEFORE calling any other initialization or RNG 805290001Sglebius * functions. 806290001Sglebius * 807290001Sglebius * (This string will _NOT_ be copied internally. Do not free it while any 808290001Sglebius * user of the secure RNG might be running. Don't pass anything other than a 809290001Sglebius * real /dev/...random device file here, or you might lose security.) 810290001Sglebius * 811290001Sglebius * This API is unstable, and might change in a future libevent version. 812290001Sglebius */ 813290001SglebiusEVENT2_EXPORT_SYMBOL 814290001Sglebiusint evutil_secure_rng_set_urandom_device_file(char *fname); 815290001Sglebius 816290001Sglebius/** Seed the random number generator with extra random bytes. 817290001Sglebius 818290001Sglebius You should almost never need to call this function; it should be 819290001Sglebius sufficient to invoke evutil_secure_rng_init(), or let Libevent take 820290001Sglebius care of calling evutil_secure_rng_init() on its own. 821290001Sglebius 822290001Sglebius If you call this function as a _replacement_ for the regular 823290001Sglebius entropy sources, then you need to be sure that your input 824290001Sglebius contains a fairly large amount of strong entropy. Doing so is 825290001Sglebius notoriously hard: most people who try get it wrong. Watch out! 826290001Sglebius 827290001Sglebius @param dat a buffer full of a strong source of random numbers 828290001Sglebius @param datlen the number of bytes to read from datlen 829290001Sglebius */ 830290001SglebiusEVENT2_EXPORT_SYMBOL 831290001Sglebiusvoid evutil_secure_rng_add_bytes(const char *dat, size_t datlen); 832290001Sglebius 833290001Sglebius#ifdef __cplusplus 834290001Sglebius} 835290001Sglebius#endif 836290001Sglebius 837290001Sglebius#endif /* EVENT1_EVUTIL_H_INCLUDED_ */ 838