Libevent provides a few APIs to use for resolving DNS names, and a facility for implementing simple DNS servers.

We’ll start by describing the higher-level facilities for name lookup, and then describe the low-level and server facilities.

There are known limitations in Libevent’s current DNS client implementation. It doesn’t support TCP lookups, DNSSec, or arbitrary record types. We’d like to fix all of these in some future version of Libevent, but for now, they’re not there.

To aid in porting programs that already use blocking name resolution, Libevent provides a portable implementation of the standard getaddrinfo() interface. This can be helpful when your program needs to run on platforms where either there is no getaddrinfo() function, or where getaddrinfo() doesn’t conform to the standard as well as our replacement. (There are shockingly many of each.)

The getaddrinfo() interface is specified in RFC 3493, section 6.1. See the "Compatibility Notes" section below for a summary of how we fall short of a conformant implemenation.

The evutil_getaddrinfo() function tries to resolve the provided nodename and servname fields, according to the rules you give it in hints, and build you a linked list of evutil_addrinfo structures and store them in *res. It returns 0 on success, and a nonzero error code on failure.

You must provide at least one of nodename and servname. If nodename is provided, it is either a literal IPv4 address (like "127.0.0.1"), a literal IPv6 address (like "::1"), or a DNS name (like "www.example.com"). If servname is provided, it is either the symbolic name of a network service (like "https") or a string containing a port number given in decimal (like "443").

If you do not specify servname, then the port values in *res will be set to zero. If you do not specify nodename, then the addresses in *res will either be for localhost (by default), or for "any" (if EVUTIL_AI_PASSIVE is set.)

The ai_flags field of hints tells evutil_getaddrinfo how to perform the lookup. It can contain zero or more of the flags below, ORed together.

The ai_family field of hints is used to tell evutil_getaddrinfo() which addresses it should return. It can be AF_INET to request IPv4 addresses only, AF_INET6 to request IPv6 addresses only, or AF_UNSPEC to request all available addresses.

The ai_socktype and ai_protocol fields of hints are used to tell evutil_getaddrinfo() how you’re going to use the address. They’re the same as the socktype and protocol fields you would pass to socket().

If evutil_getaddrinfo() is successful, it allocates a new linked list of evutil_addrinfo structures, where each points to the next with its "ai_next" pointer, and stores them in *res. Because this value is heap-allocated, you will need to use evutil_freeaddrinfo to free it.

If it fails, it returns one of these numeric error codes:

You can use evutil_gai_strerror() to convert one of these results into a human-readable string.

Note: If your OS defines struct addrinfo, then evutil_addrinfo is just an alias for your OS’s built-in structure. Similarly, if your operating system defines any of the AI_* flags, then the corresponding EVUTIL_AI_* flag is just an alias for the native flag; and if your operating system defines any of the EAI_* errors, then the corresponding EVUTIL_EAI_* code is the same as your platform’s native error code.

These functions and constants were new in Libevent 2.0.3-alpha. They are declared in event2/util.h.

The main problem with the regular getaddrinfo() interface, and with evutil_getaddrinfo() above, is that they’re blocking: when you call them, the thread you’re in has to wait while they query your DNS server(s) and wait for a response. Since you’re using Libevent, that probably isn’t the behavior you want.

So for nonblocking use, Libevent provides a set of functions to launch DNS requests, and use Libevent to wait for the server to answer.

The evdns_getaddrinfo() function behaves just like evutil_getaddrinfo(), except that instead of blocking on DNS servers, it uses Libevent’s low-level DNS facilities to look hostnames up for you. Because it can’t always return you the result immediately, you need to provide it a callback function of type evdns_getaddrinfo_cb, and an optional user-supplied argument for that callback function.

Additionally, you need to provide evdns_getaddrinfo() with a pointer to an evdns_base. This structure holds the state and configuration for Libevent’s DNS resolver. See the next section for more information on how to get one.

The evdns_getaddrinfo() function returns NULL if it fails or succeeds immediately. Otherwise, it returns a pointer to an evdns_getaddrinfo_request. You can use this to cancel the request with evdns_getaddrinfo_cancel() at any time before the request is finished.

Note that the callback function will eventually be invoked whether evdns_getaddrinfo() returns NULL or not, and whether evdns_getaddrinfo_cancel() is called or not.

When you call evdns_getaddrinfo(), it makes its own internal copies of its nodename, servname, and hints arguments: you do not need to ensure that they continue to exist while the name lookup is in progress.

These functions were new in Libevent 2.0.3-alpha. They are declared in event2/dns.h.

Before you can do nonblocking DNS lookups with evdns, you’ll need to configure an evdns_base. Each evdns_base stores a list of nameservers, and DNS configuration options, and tracks active and in-flight DNS requests.

The evdns_base_new() function returns a new evdns_base on success, and NULL on failure. If the initialize argument is 1, it tries to configure the DNS base sensibly given your operating system’s default. If it is 0, it leaves the evdns_base empty, with no nameservers or options configured.

When you no longer need an evdns_base, you can free it with evdns_base_free. If its fail_requests argument is true, it will make all in-flight requests get their callbacks invoked with a canceled error code before it frees the base.

If you want a little more control over how the evdns_base is initialized, you can pass 0 as the initialize argument to evdns_base_new, and invoke one of these functions.

The evdns_base_resolv_conf_parse() function will scan the resolv.conf formatted file stored in filename, and read in all the options from it that are listed in flags. (For more information on the resolv.conf file, see your local Unix manual pages.)

On Windows, you don’t have a resolv.conf file to tell you where your nameservers are, so you can use the evdns_base_config_windows_nameservers() function to read all your nameservers from your registry (or your NetworkParams, or wherever they’re hidden).

The resolv.conf format we recognize is a text file, each line of which should either be empty, contain a comment starting with the # character, or consist of a token followed zero or more arguments. The tokens we recognize are:

Unrecognized tokens and options are ignored.

If you want even more fine-grained control over evdns’s behavior, you can use these functions:

The evdns_base_nameserver_sockaddr_add() function adds a nameserver to an existing evdns_base by its address. The flags argument is currently ignored, and should be 0 for forward-compatibility. The function returns 0 on success and negative on failure. (It was added in Libevent 2.0.7-rc.)

The evdns_base_nameserver_ip_add function adds a nameserver to an existing evdns_base. It takes the nameserver in a text string, either as an IPv4 address, an IPv6 address, an IPv4 address with a port (IPv4:Port), or an IPv6 address with a port ([IPv6]:Port). It returns 0 on success and negative on failure.

The evdns_base_load_hosts() function loads a hosts file (in the same format as /etc/hosts) from hosts_fname. It also returns 0 on success and negative on failure.

The evdns_base_search_clear() function removes all current search suffixes (as configured by the search option) from the evdns_base; the evdns_base_search_add() function adds a suffix.

The evdns_base_set_option() function sets a given option to a given value in the evdns_base. Each one is given as a string. (Before Libevent 2.0.3, the option name needed to have a colon after it.)

If you’ve just parsed a set of configuration files and want to see if any nameservers were added, you can use evdns_base_count_nameservers() to see how many there are.

There are a couple of functions you can use to specify library-wide settings for the evdns module:

For historical reasons, the evdns subsystem does its own logging; you can use evdns_set_log_fn() to give it a callback that does something with its messages besides discard them.

For security, evdns needs a good source of random numbers: it uses this to pick hard-to-guess transaction IDs and to randomize queries when using the 0x20 hack. (See the "randomize-case" option for more info here.) Older versions of Libevent, did not provide a secure RNG of its own, however. You can give evdns a better random number generator by calling evdns_set_transaction_id_fn and giving it a function that returns a hard-to-predict two-byte unsigned integer.

In Libevent 2.0.4-alpha and later, Libevent uses its own built-in secure RNG; evdns_set_transaction_id_fn() has no effect.

Occasionally, you’ll want the ability to launch specific DNS requests with more fine-grained control than you get from evdns_getaddrinfo(). Libevent gives you some interfaces to do that.

Right now, Libevent’s DNS support lacks a few features that you’d expect from a low-level DNS system, like support for arbitrary request types and TCP requests. If you need features that evdns doesn’t have, please consider contributing a patch. You might also look into a more full-featured DNS library like c-ares.

These resolve functions initiate a DNS request for a particular record. Each takes an evdns_base to use for the request, a resource to look up (either a hostname for forward lookups, or an address for reverse lookups), a set of flags to determine how to do the lookup, a callback to invoke when the lookup is done, and a pointer to pass to the user-supplied callback.

The flags argument is either 0 or DNS_QUERY_NO_SEARCH to explicitly suppress searching in the list of search if the original search fails. DNS_QUERY_NO_SEARCH has no effect for reverse lookups, since those never do searching.

When the request is done---either successfully or not---the callback function will be invoked. The callback takes a result that indicates success or an error code (see DNS Errors table below), a record type (one of DNS_IPv4_A, DNS_IPv6_AAAA, or DNS_PTR), the number of records in addresses, a time-to-live in seconds, the addresses themselves, and the user-supplied argument pointer.

The addresses argument to the callback is NULL in the event of an error. For a PTR record, it’s a NUL-terminated string. For IPv4 records, it is an array of four-byte values in network order. For IPv6 records, it is an array of 16-byte records in network order. (Note that the number of addresses can be 0 even if there was no error. This can happen when the name exists, but it has no records of the requested type.)

The errors codes that can be passed to the callback are as follows:

[options="header",width="70%"

(DNS_ERR_NODATA was new in 2.0.15-stable.)

You can decode these error codes to a human-readable string with:

Each resolve function returns a pointer to an opaque evdns_request structure. You can use this to cancel the request at any point before the callback is invoked:

Canceling a request with this function makes its callback get invoked with the DNS_ERR_CANCEL result code.

Sometimes you want to reconfigure or shut down the DNS subsystem without affecting in-flight DNS request too much.

If you call evdns_base_clear_nameservers_and_suspend() on an evdns_base, all nameservers are removed, and pending requests are left in limbo until later you re-add nameservers and call evdns_base_resume().

These functions return 0 on success and -1 on failure. They were introduced in Libevent 2.0.1-alpha.

Libevent provides simple functionality for acting as a trivial DNS server and responding to UDP DNS requests.

This section assumes some familiarity with the DNS protocol.

To begin listening for DNS requests, call evdns_add_server_port_with_base(). It takes an event_base to use for event handling; a UDP socket to listen on; a flags variable (always 0 for now); a callback function to call when a new DNS query is received; and a pointer to user data that will be passed to the callback. It returns a new evdns_server_port object.

When you are done with the DNS server, you can pass it to evdns_close_server_port().

The evdns_add_server_port_with_base() function was new in 2.0.1-alpha; evdns_close_server_port() was introduced in 1.3.

Unfortunately, Libevent doesn’t currently provide a great way to look at DNS requests via a programmatic interface. Instead, you’re stuck including event2/dns_struct.h and looking at the evdns_server_request structure manually.

It would be great if a future version of Libevent provided a better way to do this.

The flags field of the request contains the DNS flags set in the request; the nquestions field is the number of questions in the request; and questions is an array of pointers to struct evdns_server_question. Each evdns_server_question includes the resource type of the request (see below for a list of EVDNS_*_TYPE macros), the class of the request (typically EVDNS_CLASS_INET), and the name of the requested hostname.

These structures were introduced in Libevent 1.3. Before Libevent 1.4, dns_question_class was called "class", which made trouble for the C++ people. C programs that still use the old "class" name will stop working in a future release.

Sometimes you’ll want to know which address made a particular DNS request. You can check this by calling evdns_server_request_get_requesting_addr() on it. You should pass in a sockaddr with enough storage to hold the address: struct sockaddr_storage is recommended.

This function was introduced in Libevent 1.3c.

Every time your DNS server receives a request, the request is passed to the callback function you provided, along with your user_data pointer. The callback function must either respond to the request, ignore the request, or make sure that the request is eventually answered or ignored.

Before you respond to a request, you can add one or more answers to your response:

The functions above all add a single RR (of type A, AAAA, or CNAME respectively) to the answers section of a DNS reply for the request req. In each case the argument name is the hostname to add an answer for, and ttl is the time-to-live value of the answer in seconds. For A and AAAA records, n is the number of addresses to add, and addrs is a pointer to the raw addresses, either given as a sequence of n*4 bytes for IPv4 addresses in an A record, or as a sequence of n*16 bytes for IPv6 addresses in an AAAA record.

These functions return 0 on success and -1 on failure.

This function adds a PTR record to the answer section of a request. The arguments req and ttl are as above. You must provide exactly one of in (an IPv4 address) or inaddr_name (an address in the .arpa domain) to indicate which address you’re providing a response for. The hostname argument is the answer for the PTR lookup.

This function adds an arbitrary RR to the DNS reply of a request req. The section argument describes which section to add it to, and should be one of the EVDNS_*_SECTION values. The name argument is the name field of the RR. The type argument is the type field of the RR, and should be one of the EVDNS_TYPE_* values if possible. The dns_class argument is the class field of the RR, and should generally be EVDNS_CLASS_INET. The ttl argument is the time-to-live in seconds of the RR. The rdata and rdlength fields of the RR will be generated from the datalen bytes provided in data. If is_name is true, the data will be encoded as a DNS name (i.e., with DNS name compression). Otherwise, it’s included verbatim.

The evdns_server_request_respond() function sends a DNS response to a request, including all of the RRs that you attached to it, with the error code err. If you get a request that you don’t want to respond to, you can ignore it by calling evdns_server_request_drop() on it to release all the associated memory and bookkeeping structures.

If you want to set any flags on your response message, you can call this function at any time before you send the response.

All the functions in this section were introduced in Libevent 1.3, except for evdns_server_request_set_flags() which first appeared in Libevent 2.0.1-alpha.

Calling evdns_base_search_ndots_set() is equivalent to using evdns_base_set_option() with the "ndots" option.

The evdns_base_nameserver_add() function behaves as evdns_base_nameserver_ip_add(), except it can only add nameservers with IPv4 addresses. It takes them, idiosyncratically, as four bytes in network order.

Before Libevent 2.0.1-alpha, there was no way to specify a event base for a DNS server port. You had to use evdns_add_server_port() instead, which took the default event_base.

From Libevent 2.0.1-alpha through 2.0.3-alpha, you could use evdns_set_random_bytes_fn to specify a function to use for generating random numbers instead of evdns_set_transaction_id_fn. It no longer has any effect, now that Libevent provides its own secure RNG.

The DNS_QUERY_NO_SEARCH flag has also been called DNS_NO_SEARCH.

Before Libevent 2.0.1-alpha, there was no separate notion of an evdns_base: all information in the evdns subsystem was stored globally, and the functions that manipulated it took no evdns_base as an argument. They are all now deprecated, and declared only in event2/dns_compat.h. They are implemented via a single global evdns_base; you can access this base by calling the evdns_get_global_base() function introduced in Libevent 2.0.3-alpha.

The EVDNS_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED macro is defined if and only if evdns_config_windows_nameservers() is available.