The <event2/util.h> header defines many functions that you might find helpful for implementing portable applications using Libevent. Libevent uses these types and functions internally.

Most everywhere except Windows, a socket is an int, and the operating system hands them out in numeric order. Using the Windows socket API, however, a socket is of type SOCKET, which is really a pointer-like OS handle, and the order you receive them is undefined. We define the evutil_socket_t type to be an integer that can hold the output of socket() or accept() without risking pointer truncation on Windows.

This type was introduced in Libevent 2.0.1-alpha.

Often you will find yourself on a C system that missed out on the 21st century and therefore does not implement the standard C99 stdint.h header. For this situation, Libevent defines its own versions of the bit-width-specific integers from stdint.h:

As in the C99 standard, each type has exactly the specified width, in bits.

These types were introduced in Libevent 1.4.0-beta. The MAX/MIN constants first appeared in Libevent 2.0.4-alpha.

The ev_ssize_t type is defined to ssize_t (signed size_t) on platforms that have one, and to a reasonable default on platforms that don’t. The largest possible value of ev_ssize_t is EV_SSIZE_MAX; the smallest is EV_SSIZE_MIN. (The largest possible value for size_t is EV_SIZE_MAX, in case your platform doesn’t define a SIZE_MAX for you.)

The ev_off_t type is used to represent offset into a file or a chunk of memory. It is defined to off_t on platforms with a reasonable off_t definition, and to ev_int64_t on Windows.

Some implementations of the sockets API provide a length type, socklen_t, and some do not. The ev_socklen_t is defined to this type where it exists, and a reasonable default otherwise.

The ev_intptr_t type is a signed integer that is large enough to hold a pointer without loss of bits. The ev_uintptr_t type is an unsigned integer large enough to hold a pointer without loss of bits.

The ev_ssize_t type was added in Libevent 2.0.2-alpha. The ev_socklen_t type was new in Libevent 2.0.3-alpha. The ev_intptr_t and ev_uintptr_t types, and the EV_SSIZE_MAX/MIN macros, were added in Libevent 2.0.4-alpha. The ev_off_t type first appeared in Libevent 2.0.9-rc.

Not every platform defines the standard timeval manipulation functions, so we provide our own implementations.

These macros add or subtract (respectively) their first two arguments, and stores the result in the third.

Clearing a timeval sets its value to zero. Checking whether it is set returns true if it is nonzero and false otherwise.

The evutil_timercmp macro compares two timevals, and yields true if they are in the relationship specified by the relational operator cmp. For example, evutil_timercmp(t1, t2, ⇐) means, "Is t1 ⇐ t2?" Note that unlike some operating systems' versions, Libevent’s timercmp supports all the C relational operations (that is, <, >, ==, !=, ⇐, and >=).

The evutil_gettimeofday function sets tv to the current time. The tz argument is unused.

These functions were introduced in Libevent 1.4.0-beta, except for evutil_gettimeofday(), which was introduced in Libevent 2.0.

This section exists because, for historical reasons, Windows has never really implemented the Berkeley sockets API in a nice compatible (and nicely compatible) way. Here are some functions you can use in order to pretend that it has.

This function closes a socket. On Unix, it’s an alias for close(); on Windows, it calls closesocket(). (You can’t use close() on sockets on Windows, and nobody else defines a closesocket().)

The evutil_closesocket function was introduced in Libevent 2.0.5-alpha. Before then, you needed to call the EVUTIL_CLOSESOCKET macro.

These macros access and manipulate socket error codes. EVUTIL_SOCKET_ERROR() returns the global error code for the last socket operation from this thread, and evutil_socket_geterror() does so for a particular socket. (Both are errno on Unix-like systems.) EVUTIL_SET_SOCKET_ERROR() changes the current socket error code (like setting errno on Unix), and evutil_socket_error_to_string() returns a string representation of a given socket error code (like strerror() on Unix).

(We need these functions because Windows doesn’t use errno for errors from socket functions, but instead uses WSAGetLastError().)

Note that the Windows socket errors are not the same as the standard-C errors you would see in errno; watch out.

Even the call you need to do nonblocking IO on a socket is not portable to Windows. The evutil_make_socket_nonblocking() function takes a new socket (from socket() or accept()) and turns it into a nonblocking socket. (It sets O_NONBLOCK on Unix and FIONBIO on Windows.)

This function makes sure that the address used by a listener socket will be available to another socket immediately after the socket is closed. (It sets SO_REUSEADDR on Unix and does nothing on Windows. You don’t want to use SO_REUSEADDR on Windows; it means something different there.)

This call tells the operating system that this socket should be closed if we ever call exec(). It sets the FD_CLOEXEC flag on Unix, and does nothing on Windows.

This function behaves as the Unix socketpair() call: it makes two sockets that are connected with each other and can be used with ordinary socket IO calls. It stores the two sockets in sv[0] and sv[1], and returns 0 for success and -1 for failure.

On Windows, this only supports family AF_INET, type SOCK_STREAM, and protocol 0. Note that this can fail on some Windows hosts where firewall software has cleverly firewalled 127.0.0.1 to keep the host from talking to itself.

These functions were introduced in Libevent 1.4.0-beta, except for evutil_make_socket_closeonexec(), which was new in Libevent 2.0.4-alpha.

This function behaves as strtol, but handles 64-bit integers. On some platforms, it only supports Base 10.

These snprintf-replacement functions behave as the standard snprintf and vsnprintf interfaces. They return the number of bytes that would have been written into the buffer had it been long enough, not counting the terminating NUL byte. (This behavior conforms to the C99 snprintf() standard, and is in contrast to the Windows _snprintf(), which returns a negative number if the string would not fit in the buffer.)

The evutil_strtoll() function has been in Libevent since 1.4.2-rc. These other functions first appeared in version 1.4.5.

Sometimes, when implementing ASCII-based protocols, you want to manipulate strings according to ASCII’s notion of character type, regardless of your current locale. Libevent provides a few functions to help with this:

These functions behave as strcasecmp() and strncasecmp(), except that they always compare using the ASCII character set, regardless of the current locale. The evutil_ascii_str[n]casecmp() functions were first exposed in Libevent 2.0.3-alpha.

These functions behave as the standard inet_ntop() and inet_pton() functions for parsing and formatting IPv4 and IPv6 addresses, as specified in RFC3493. That is, to format an IPv4 address, you call evutil_inet_ntop() with af set to AF_INET, src pointing to a struct in_addr, and dst pointing to a character buffer of size len. For an IPv6 address, af is AF_INET6 and src is a struct in6_addr. To parse an IPv4 address, call evutil_inet_pton() with af set to AF_INET or AF_INET6, the string to parse in src, and dst pointing to an in_addr or an in_addr6 as appropriate.

The return value from evutil_inet_ntop() is NULL on failure and otherwise points to dst. The return value from evutil_inet_pton() is 0 on success and -1 on failure.

This function parses an address from str and writes the result to out. The outlen argument must point to an integer holding the number of bytes available in out; it is altered to hold the number of bytes actually used. This function returns 0 on success and -1 on failure. It recognizes the following address formats:

If no port is given, the port in the resulting sockaddr is set to 0.

The evutil_sockaddr_cmp() function compares two addresses, and returns negative if sa1 precedes sa2, 0 if they are equal, and positive if sa2 precedes sa1. It works for AF_INET and AF_INET6 addresses, and returns undefined output for other addresses. It’s guaranteed to give a total order for these addresses, but the ordering may change between Libevent versions.

If the include_port argument is false, then two sockaddrs are treated as equal if they differ only in their port. Otherwise, sockaddrs with different ports are treated as unequal.

These functions were introduced in Libevent 2.0.1-alpha, except for evutil_sockaddr_cmp(), which introduced in 2.0.3-alpha.

As the standard offsetof macro, this macro yields the number of bytes from the start of type at which field occurs.

This macro was introduced in Libevent 2.0.1-alpha. It was buggy in every version before Libevent 2.0.3-alpha.

Many applications (including evdns) need a source of hard-to-predict random numbers for their security.

This function fills n-byte buffer at buf with n bytes of random data.

If your platform provides the arc4random() function, Libevent uses that. Otherwise, it uses its own implementation of arc4random(), seeded by your operating system’s entropy pool (CryptGenRandom on Windows, /dev/urandom everywhere else).

You do not need to manually initialize the secure random number generator, but if you want to make sure it is successfully initialized, you can do so by calling evutil_secure_rng_init(). It seeds the RNG (if it was not already seeded) and returns 0 on success. If it returns -1, Libevent wasn’t able to find a good source of entropy on your OS, and you can’t use the RNG safely without initializing it yourself.

If you are running in an environment where your program is likely to drop privileges (for example, by running chroot()), you should call evutil_secure_rng_init() before you do so.

You can add more random bytes to the entropy pool yourself by calling evutil_secure_rng_add_bytes(); this shouldn’t be necessary in typical use.

These functions are new in Libevent 2.0.4-alpha.