Common convenience functions for cross-platform portability and related socket manipulations. More...

#include <event2/event-config.h>
#include <stdarg.h>
#include <sys/socket.h>

Data Structures
struct	evutil_addrinfo
Defines
#define	EV_INT16_MAX ((ev_int16_t) 0x7fffL)
#define	EV_INT16_MIN ((-EV_INT16_MAX) - 1)
#define	EV_INT32_MAX ((ev_int32_t) 0x7fffffffL)
#define	EV_INT32_MIN ((-EV_INT32_MAX) - 1)
#define	EV_INT64_MAX ((((ev_int64_t) 0x7fffffffL) << 32) \| 0xffffffffL)
#define	EV_INT64_MIN ((-EV_INT64_MAX) - 1)
#define	EV_INT8_MAX 127
#define	EV_INT8_MIN ((-EV_INT8_MAX) - 1)
#define	ev_int8_t signed char
#define	ev_intptr_t ev_int32_t
#define	ev_off_t off_t
#define	ev_socklen_t socklen_t
#define	EV_SSIZE_MIN ((-EV_SSIZE_MAX) - 1)
#define	ev_ssize_t ssize_t
#define	EV_UINT16_MAX ((ev_uint16_t)0xffffUL)
#define	EV_UINT32_MAX ((ev_uint32_t)0xffffffffUL)
#define	EV_UINT64_MAX ((((ev_uint64_t)0xffffffffUL) << 32) \| 0xffffffffUL)
#define	EV_UINT8_MAX 255
#define	ev_uint8_t unsigned char
#define	ev_uintptr_t ev_uint32_t
#define	EVUTIL_AI_ADDRCONFIG 0x40000
#define	EVUTIL_AI_ALL 0x20000
#define	EVUTIL_AI_CANONNAME 0x2000
#define	EVUTIL_AI_NUMERICHOST 0x4000
#define	EVUTIL_AI_NUMERICSERV 0x8000
#define	EVUTIL_AI_PASSIVE 0x1000
#define	EVUTIL_AI_V4MAPPED 0x10000
#define	EVUTIL_CLOSESOCKET(s) evutil_closesocket(s)
#define	EVUTIL_EAI_ADDRFAMILY -901
#define	EVUTIL_EAI_AGAIN -902
#define	EVUTIL_EAI_BADFLAGS -903
#define	EVUTIL_EAI_CANCEL -90001
#define	EVUTIL_EAI_FAIL -904
#define	EVUTIL_EAI_FAMILY -905
#define	EVUTIL_EAI_MEMORY -906
#define	EVUTIL_EAI_NODATA -907
#define	EVUTIL_EAI_NONAME -908
#define	EVUTIL_EAI_SERVICE -909
#define	EVUTIL_EAI_SOCKTYPE -910
#define	EVUTIL_EAI_SYSTEM -911
#define	evutil_offsetof(type, field) ((off_t)(&((type *)0)->field))
#define	EVUTIL_SET_SOCKET_ERROR(errcode) do { errno = (errcode); } while (0)
#define	EVUTIL_SOCKET_ERROR() (errno)
#define	evutil_socket_error_to_string(errcode) (strerror(errcode))
#define	evutil_socket_geterror(sock) (errno)
#define	evutil_socket_t int
#define	evutil_timeradd(tvp, uvp, vvp)
#define	evutil_timerclear(tvp) (tvp)->tv_sec = (tvp)->tv_usec = 0
#define	evutil_timercmp(tvp, uvp, cmp)
	Return true iff the tvp is related to uvp according to the relational operator cmp.
#define	evutil_timerisset(tvp) ((tvp)->tv_sec \|\| (tvp)->tv_usec)
#define	evutil_timersub(tvp, uvp, vvp)
Functions
int	evutil_ascii_strcasecmp (const char str1, const char str2)
	As strcasecmp, but always compares the characters in locale-independent ASCII.
int	evutil_ascii_strncasecmp (const char str1, const char str2, size_t n)
	As strncasecmp, but always compares the characters in locale-independent ASCII.
int	evutil_closesocket (evutil_socket_t sock)
	Do the platform-specific call needed to close a socket returned from socket() or accept().
void	evutil_freeaddrinfo (struct evutil_addrinfo *ai)
const char *	evutil_gai_strerror (int err)
int	evutil_getaddrinfo (const char nodename, const char servname, const struct evutil_addrinfo hints_in, struct evutil_addrinfo *res)
int	evutil_gettimeofday (struct timeval tv, struct timezone tz)
const char *	evutil_inet_ntop (int af, const void src, char dst, size_t len)
	Replacement for inet_ntop for platforms which lack it.
int	evutil_inet_pton (int af, const char src, void dst)
	Replacement for inet_pton for platforms which lack it.
int	evutil_make_listen_socket_reuseable (evutil_socket_t sock)
	Do platform-specific operations on a listener socket to make sure that another program will be able to bind this address right after we've closed the listener.
int	evutil_make_socket_closeonexec (evutil_socket_t sock)
	Do platform-specific operations as needed to close a socket upon a successful execution of one of the exec*() functions.
int	evutil_make_socket_nonblocking (evutil_socket_t sock)
	Do platform-specific operations as needed to make a socket nonblocking.
int	evutil_parse_sockaddr_port (const char str, struct sockaddr out, int *outlen)
	Parse an IPv4 or IPv6 address, with optional port, from a string.
void	evutil_secure_rng_add_bytes (const char *dat, size_t datlen)
	Seed the random number generator with extra random bytes.
void	evutil_secure_rng_get_bytes (void *buf, size_t n)
int	evutil_secure_rng_init (void)
	Seed the secure random number generator if needed, and return 0 on success or -1 on failure.
int	evutil_snprintf (char buf, size_t buflen, const char format,...)
	Replacement for snprintf to get consistent behavior on platforms for which the return value of snprintf does not conform to C99.
int	evutil_sockaddr_cmp (const struct sockaddr sa1, const struct sockaddr sa2, int include_port)
	Compare two sockaddrs; return 0 if they are equal, or less than 0 if sa1 preceeds sa2, or greater than 0 if sa1 follows sa2.
int	evutil_socketpair (int d, int type, int protocol, evutil_socket_t sv[2])
	Create two new sockets that are connected to each other.
ev_int64_t	evutil_strtoll (const char s, char *endptr, int base)
	Parse a 64-bit value from a string.
int	evutil_vsnprintf (char buf, size_t buflen, const char format, va_list ap)

Detailed Description

Common convenience functions for cross-platform portability and related socket manipulations.

Define Documentation

#define evutil_timeradd	(	tvp,
		uvp,
		vvp
	)

Value:

do {                                                            \
                (vvp)->tv_sec = (tvp)->tv_sec + (uvp)->tv_sec;          \
                (vvp)->tv_usec = (tvp)->tv_usec + (uvp)->tv_usec;       \
                if ((vvp)->tv_usec >= 1000000) {                        \
                        (vvp)->tv_sec++;                                \
                        (vvp)->tv_usec -= 1000000;                      \
                }                                                       \
        } while (0)

#define evutil_timercmp	(	tvp,
		uvp,
		cmp
	)

Value:

(((tvp)->tv_sec == (uvp)->tv_sec) ?                             \
         ((tvp)->tv_usec cmp (uvp)->tv_usec) :                          \
         ((tvp)->tv_sec cmp (uvp)->tv_sec))

Return true iff the tvp is related to uvp according to the relational operator cmp.

Recognized values for cmp are ==, <=, <, >=, and >.

#define evutil_timersub	(	tvp,
		uvp,
		vvp
	)

Value:

do {                                                            \
                (vvp)->tv_sec = (tvp)->tv_sec - (uvp)->tv_sec;          \
                (vvp)->tv_usec = (tvp)->tv_usec - (uvp)->tv_usec;       \
                if ((vvp)->tv_usec < 0) {                               \
                        (vvp)->tv_sec--;                                \
                        (vvp)->tv_usec += 1000000;                      \
                }                                                       \
        } while (0)

Function Documentation

int evutil_ascii_strcasecmp	(	const char *	str1,
		const char *	str2
	)

As strcasecmp, but always compares the characters in locale-independent ASCII.

That's useful if you're handling data in ASCII-based protocols.

int evutil_ascii_strncasecmp	(	const char *	str1,
		const char *	str2,
		size_t	n
	)

As strncasecmp, but always compares the characters in locale-independent ASCII.

That's useful if you're handling data in ASCII-based protocols.

int evutil_closesocket ( evutil_socket_t sock )

Do the platform-specific call needed to close a socket returned from socket() or accept().

Parameters:

sock	The socket to be closed

Returns:: 0 on success, -1 on failure

const char* evutil_inet_ntop	(	int	af,
		const void *	src,
		char *	dst,
		size_t	len
	)

Replacement for inet_ntop for platforms which lack it.

int evutil_inet_pton	(	int	af,
		const char *	src,
		void *	dst
	)

Replacement for inet_pton for platforms which lack it.

int evutil_make_listen_socket_reuseable ( evutil_socket_t sock )

Do platform-specific operations on a listener socket to make sure that another program will be able to bind this address right after we've closed the listener.

Parameters:

sock	The socket to make reusable

Returns:: 0 on success, -1 on failure

int evutil_make_socket_closeonexec ( evutil_socket_t sock )

Do platform-specific operations as needed to close a socket upon a successful execution of one of the exec*() functions.

Parameters:

sock	The socket to be closed

Returns:: 0 on success, -1 on failure

int evutil_make_socket_nonblocking ( evutil_socket_t sock )

Do platform-specific operations as needed to make a socket nonblocking.

Parameters:

sock	The socket to make nonblocking

Returns:: 0 on success, -1 on failure

int evutil_parse_sockaddr_port	(	const char *	str,
		struct sockaddr *	out,
		int *	outlen
	)

Parse an IPv4 or IPv6 address, with optional port, from a string.

Recognized formats are:

[IPv6Address]:port
[IPv6Address]
IPv6Address
IPv4Address:port
IPv4Address

If no port is specified, the port in the output is set to 0.

Parameters:

str	The string to parse.
out	A struct sockaddr to hold the result. This should probably be a struct sockaddr_storage.
outlen	A pointer to the number of bytes that that 'out' can safely hold. Set to the number of bytes used in 'out' on success.

Returns:: -1 if the address is not well-formed, if the port is out of range, or if out is not large enough to hold the result. Otherwise returns 0 on success.

void evutil_secure_rng_add_bytes	(	const char *	dat,
		size_t	datlen
	)

Seed the random number generator with extra random bytes.

You should almost never need to call this function; it should be sufficient to invoke evutil_secure_rng_init(), or let Libevent take care of calling evutil_secure_rng_init() on its own.

If you call this function as a _replacement_ for the regular entropy sources, then you need to be sure that your input contains a fairly large amount of strong entropy. Doing so is notoriously hard: most people who try get it wrong. Watch out!

Parameters:

dat	a buffer full of a strong source of random numbers
datlen	the number of bytes to read from datlen

int evutil_secure_rng_init ( void )

Seed the secure random number generator if needed, and return 0 on success or -1 on failure.

It is okay to call this function more than once; it will still return 0 if the RNG has been successfully seeded and -1 if it can't be seeded.

Ordinarily you don't need to call this function from your own code; Libevent will seed the RNG itself the first time it needs good random numbers. You only need to call it if (a) you want to double-check that one of the seeding methods did succeed, or (b) you plan to drop the capability to seed (by chrooting, or dropping capabilities, or whatever), and you want to make sure that seeding happens before your program loses the ability to do it.

int evutil_sockaddr_cmp	(	const struct sockaddr *	sa1,
		const struct sockaddr *	sa2,
		int	include_port
	)

Compare two sockaddrs; return 0 if they are equal, or less than 0 if sa1 preceeds sa2, or greater than 0 if sa1 follows sa2.

If include_port is true, consider the port as well as the address. Only implemented for AF_INET and AF_INET6 addresses. The ordering is not guaranteed to remain the same between Libevent versions.

int evutil_socketpair	(	int	d,
		int	type,
		int	protocol,
		evutil_socket_t	sv[2]
	)

Create two new sockets that are connected to each other.

On Unix, this simply calls socketpair(). On Windows, it uses the loopback network interface on 127.0.0.1, and only AF_INET,SOCK_STREAM are supported.

(This may fail on some Windows hosts where firewall software has cleverly decided to keep 127.0.0.1 from talking to itself.)

Parameters and return values are as for socketpair()

ev_int64_t evutil_strtoll	(	const char *	s,
		char **	endptr,
		int	base
	)

Parse a 64-bit value from a string.

Arguments are as for strtol.

include/event2/util.h File Reference

Data Structures

Defines

Functions

Detailed Description

Define Documentation

Function Documentation