I would appreciate any donations. Wishlist or send e-mail type donations to maekawa AT daemon-systems.org.

Thank you.


evutil(3)                  Library Functions Manual                  evutil(3)



NAME
       evutil -

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


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


   Data Structures
           struct evutil_addrinfo
           A definition of struct addrinfo for systems that lack it.

   Macros
           #define ev_socklen_t   socklen_t
           #define EVUTIL_CLOSESOCKET(s)   evutil_closesocket(s)
           #define evutil_offsetof(type, field)   ((off_t)(&((type
           *)0)->field))
           Replacement for offsetof on platforms that don't define it.
           #define evutil_socket_t   int
           A type wide enough to hold the output of 'socket()' or 'accept()'.
           #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)

       Standard integer types.
       Integer type definitions for types that are supposed to be defined in
       the C99-specified stdint.h.

       Shamefully, some platforms do not include stdint.h, so we need to
       replace it. (If you are on a platform like this, your C headers are now
       over 10 years out of date. You should bug them to do something about
       this.)

       We define:

       ev_uint64_t, ev_uint32_t, ev_uint16_t, ev_uint8_t
           unsigned integer types of exactly 64, 32, 16, and 8 bits
           respectively.

       ev_int64_t, ev_int32_t, ev_int16_t, ev_int8_t
           signed integer types of exactly 64, 32, 16, and 8 bits
           respectively.

       ev_uintptr_t, ev_intptr_t
           unsigned/signed integers large enough to hold a pointer without
           loss of bits.

       ev_ssize_t
           A signed type of the same size as size_t

       ev_off_t
           A signed type typically used to represent offsets within a
           (potentially large) file


               #define ev_uint64_t   ...
               #define ev_int64_t   ...
               #define ev_uint32_t   ...
               #define ev_int32_t   ...
               #define ev_uint16_t   ...
               #define ev_int16_t   ...
               #define ev_uint8_t   ...
               #define ev_int8_t   ...
               #define ev_uintptr_t   ev_uint32_t
               #define ev_intptr_t   ev_int32_t
               #define ev_ssize_t   ssize_t
               #define ev_off_t   off_t

       Limits for integer types
       These macros hold the largest or smallest values possible for the
       ev_[u]int*_t types.

               #define EV_UINT64_MAX   ((((ev_uint64_t)0xffffffffUL) << 32) |
               0xffffffffUL)
               #define EV_INT64_MAX   ((((ev_int64_t) 0x7fffffffL) << 32) |
               0xffffffffL)
               #define EV_INT64_MIN   ((-EV_INT64_MAX) - 1)
               #define EV_UINT32_MAX   ((ev_uint32_t)0xffffffffUL)
               #define EV_INT32_MAX   ((ev_int32_t) 0x7fffffffL)
               #define EV_INT32_MIN   ((-EV_INT32_MAX) - 1)
               #define EV_UINT16_MAX   ((ev_uint16_t)0xffffUL)
               #define EV_INT16_MAX   ((ev_int16_t) 0x7fffL)
               #define EV_INT16_MIN   ((-EV_INT16_MAX) - 1)
               #define EV_UINT8_MAX   255
               #define EV_INT8_MAX   127
               #define EV_INT8_MIN   ((-EV_INT8_MAX) - 1)

       Limits for SIZE_T and SSIZE_T

               #define EV_SIZE_MAX   ...
               #define EV_SSIZE_MAX   ...
               #define EV_SSIZE_MIN   ((-EV_SSIZE_MAX) - 1)

       Socket error functions
       These functions are needed for making programs compatible between
       Windows and Unix-like platforms.

       You see, Winsock handles socket errors differently from the rest of the
       world. Elsewhere, a socket error is like any other error and is stored
       in errno. But winsock functions require you to retrieve the error with
       a special function, and don't let you use strerror for the error codes.
       And handling EWOULDBLOCK is ... different.

               #define EVUTIL_SOCKET_ERROR()   ...
               Return the most recent socket error.  #define
               EVUTIL_SET_SOCKET_ERROR(errcode)   ...
               Replace the most recent socket error with errcode.  #define
               evutil_socket_geterror(sock)   ...
               Return the most recent socket error to occur on sock.  #define
               evutil_socket_error_to_string(errcode)   ...
               Convert a socket error to a string.

       Manipulation macros for struct timeval.
       We define replacements for timeradd, timersub, timerclear, timercmp,
       and timerisset.

               #define evutil_timeradd(tvp, uvp, vvp)
               #define evutil_timersub(tvp, uvp, vvp)
               #define evutil_timerclear(tvp)   (tvp)->tv_sec = (tvp)->tv_usec
               = 0

       evutil_getaddrinfo() error codes
       These values are possible error codes for evutil_getaddrinfo() and
       related functions.

               #define EVUTIL_EAI_ADDRFAMILY   -901
               #define EVUTIL_EAI_AGAIN   -902
               #define EVUTIL_EAI_BADFLAGS   -903
               #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_EAI_CANCEL   -90001
               #define EVUTIL_AI_PASSIVE   0x1000
               #define EVUTIL_AI_CANONNAME   0x2000
               #define EVUTIL_AI_NUMERICHOST   0x4000
               #define EVUTIL_AI_NUMERICSERV   0x8000
               #define EVUTIL_AI_V4MAPPED   0x10000
               #define EVUTIL_AI_ALL   0x20000
               #define EVUTIL_AI_ADDRCONFIG   0x40000

   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)
           Release storage allocated by evutil_getaddrinfo or
           evdns_getaddrinfo.  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)
           This function clones getaddrinfo for systems that don't have it.
           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 to make a listener socket reusable.
           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)
           Generate n bytes of secure pseudorandom data, and store them in
           buf.  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)
           Replacement for vsnprintf to get consistent behavior on platforms
           for which the return value of snprintf does not conform to C99.

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



Macro Definition Documentation
   #define evutil_offsetof(type, field)   ((off_t)(&((type *)0)->field))
       Replacement for offsetof on platforms that don't define it.

   #define EVUTIL_SOCKET_ERROR()   ...
       Return the most recent socket error. Not idempotent on all platforms.

   #define evutil_socket_error_to_string(errcode)   ...
       Convert a socket error to a string.

   #define evutil_socket_geterror(sock)   ...
       Return the most recent socket error to occur on sock.

   #define evutil_socket_t   int
       A type wide enough to hold the output of 'socket()' or 'accept()'. On
       Windows, this is an intptr_t; elsewhere, it is an int.

   #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 (/*CONSTCOND*/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 (/*CONSTCOND*/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_tn)
       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_tsock)
       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


   void evutil_freeaddrinfo (struct evutil_addrinfo *ai)
       Release storage allocated by evutil_getaddrinfo or evdns_getaddrinfo.

   int evutil_getaddrinfo (const char *nodename, const char *servname, const
   struct evutil_addrinfo *hints_in, struct evutil_addrinfo **res)
       This function clones getaddrinfo for systems that don't have it. For
       full details, see RFC 3493, section 6.1.

       Limitations:

       o When the system has no getaddrinfo, we fall back to gethostbyname_r
         or gethostbyname, with their attendant issues.

       o The AI_V4MAPPED and AI_ALL flags are not currently implemented.

       For a nonblocking variant, see evdns_getaddrinfo.

   const char* evutil_inet_ntop (intaf, const void *src, char *dst, size_tlen)
       Replacement for inet_ntop for platforms which lack it.

   int evutil_inet_pton (intaf, const char *src, void *dst)
       Replacement for inet_pton for platforms which lack it.

   int evutil_make_listen_socket_reuseable (evutil_socket_tsock)
       Do platform-specific operations to make a listener socket reusable.
       Specifically, we want to make sure that another program will be able to
       bind this address right after we've closed the listener.

       This differs from Windows's interpretation of 'reusable', which allows
       multiple listeners to bind the same address at the same time.

       Parameters:
           sock The socket to make reusable

       Returns:
           0 on success, -1 on failure


   int evutil_make_socket_closeonexec (evutil_socket_tsock)
       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_tsock)
       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:

       o [IPv6Address]:port

       o [IPv6Address]

       o IPv6Address

       o IPv4Address:port

       o 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_tdatlen)
       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


   void evutil_secure_rng_get_bytes (void *buf, size_tn)
       Generate n bytes of secure pseudorandom data, and store them in buf. By
       default, Libevent uses an ARC4-based random number generator, seeded
       using the platform's entropy source (/dev/urandom on Unix-like systems;
       CryptGenRandom on Windows).

   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, intinclude_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 (intd, inttype, intprotocol, evutil_socket_tsv[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, intbase)
       Parse a 64-bit value from a string. Arguments are as for strtol.

Author
       Generated automatically by Doxygen for libevent from the source code.



libevent                        Wed Apr 10 2013                      evutil(3)