1EVDNS(3) BSD Library Functions Manual EVDNS(3)
2
4 evdns_init evdns_shutdown evdns_err_to_string evdns_nameserver_add
5 evdns_count_nameservers evdns_clear_nameservers_and_suspend evdns_resume
6 evdns_nameserver_ip_add evdns_resolve_ipv4 evdns_resolve_reverse
7 evdns_resolv_conf_parse evdns_config_windows_nameservers
8 evdns_search_clear evdns_search_add evdns_search_ndots_set
9 evdns_set_log_fn — asynchronous functions for DNS resolution.
10
12 #include <sys/time.h>
13 #include <event.h>
14 #include <evdns.h>
15 int
17 evdns_init();
18 void
20 evdns_shutdown(int fail_requests);
21 const char *
23 evdns_err_to_string(int err);
24 int
26 evdns_nameserver_add(unsigned long int address);
27 int
29 evdns_count_nameservers();
30 int
32 evdns_clear_nameservers_and_suspend();
33 int
35 evdns_resume();
36 int
38 evdns_nameserver_ip_add(const(char, *ip_as_string););
39 int
41 evdns_resolve_ipv4(const char *name, int flags,
42 evdns_callback_type callback, void *ptr);
43 int
45 evdns_resolve_reverse(struct in_addr *in, int flags,
46 evdns_callback_type callback, void *ptr);
47 int
49 evdns_resolv_conf_parse(int flags, const char *);
50 void
52 evdns_search_clear();
53 void
55 evdns_search_add(const char *domain);
56 void
58 evdns_search_ndots_set(const int ndots);
59 void
61 evdns_set_log_fn(evdns_debug_log_fn_type fn);
62 int
64 evdns_config_windows_nameservers();
65
67 Welcome, gentle reader
68 Async DNS lookups are really a whole lot harder than they should be,
70 mostly stemming from the fact that the libc resolver has never been very
71 good at them. Before you use this library you should see if libc can do
72 the job for you with the modern async call getaddrinfo_a (see
73 http://www.imperialviolet.org/page25.html#e498). Otherwise, please con‐
74 tinue.
75 This code is based on libevent and you must call event_init before any of
77 the APIs in this file. You must also seed the OpenSSL random source if
78 you are using OpenSSL for ids (see below).
79 This library is designed to be included and shipped with your source
81 code. You statically link with it. You should also test for the existence
82 of strtok_r and define HAVE_STRTOK_R if you have it.
83 The DNS protocol requires a good source of id numbers and these numbers
85 should be unpredictable for spoofing reasons. There are three methods for
86 generating them here and you must define exactly one of them. In increas‐
87 ing order of preference:
88 DNS_USE_GETTIMEOFDAY_FOR_ID Using the bottom 16 bits of the usec
90 result from gettimeofday. This is a
91 pretty poor solution but should work
92 anywhere.
93 DNS_USE_CPU_CLOCK_FOR_ID Using the bottom 16 bits of the nsec
94 result from the CPU's time counter.
95 This is better, but may not work
96 everywhere. Requires POSIX realtime
97 support and you'll need to link
98 against -lrt on glibc systems at
99 least.
100 DNS_USE_OPENSSL_FOR_ID Uses the OpenSSL RAND_bytes call to
101 generate the data. You must have
102 seeded the pool before making any
103 calls to this library.
104 The library keeps track of the state of nameservers and will avoid them
106 when they go down. Otherwise it will round robin between them.
107 Quick start guide:
109 #include "evdns.h"
110 void callback(int result, char type, int count, int ttl, void
111 *addresses, void *arg);
112 evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
113 evdns_resolve("www.hostname.com", 0, callback, NULL);
114 When the lookup is complete the callback function is called. The first
116 argument will be one of the DNS_ERR_* defines in evdns.h. Hopefully it
117 will be DNS_ERR_NONE, in which case type will be DNS_IPv4_A, count will
118 be the number of IP addresses, ttl is the time which the data can be
119 cached for (in seconds), addresses will point to an array of uint32_t's
120 and arg will be whatever you passed to evdns_resolve.
121 Searching:
123 In order for this library to be a good replacement for glibc's resolver
125 it supports searching. This involves setting a list of default domains,
126 in which names will be queried for. The number of dots in the query name
127 determines the order in which this list is used.
128 Searching appears to be a single lookup from the point of view of the
130 API, although many DNS queries may be generated from a single call to
131 evdns_resolve. Searching can also drastically slow down the resolution of
132 names.
133 To disable searching:
135 1. Never set it up. If you never call evdns_resolv_conf_parse,()
136 evdns_init,() or evdns_search_add() then no searching will
137 occur.
138 2. If you do call evdns_resolv_conf_parse() then don't pass
139 DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it).
140 3. When calling evdns_resolve,() pass the DNS_QUERY_NO_SEARCH
141 flag.
142 The order of searches depends on the number of dots in the name. If the
144 number is greater than the ndots setting then the names is first tried
145 globally. Otherwise each search domain is appended in turn.
146 The ndots setting can either be set from a resolv.conf, or by calling
148 evdns_search_ndots_set.
149 For example, with ndots set to 1 (the default) and a search domain list
151 of ["myhome.net"]:
152 Query: www
153 Order: www.myhome.net, www.
154 Query: www.abc
156 Order: www.abc., www.abc.myhome.net
157
159 int evdns_init()
160 Initializes support for non-blocking name resolution by calling
161 evdns_resolv_conf_parse() on UNIX and
162 evdns_config_windows_nameservers() on Windows.
163 int evdns_nameserver_add(unsigned long int address)
165 Add a nameserver. The address should be an IP address in network
166 byte order. The type of address is chosen so that it matches
167 in_addr.s_addr. Returns non-zero on error.
168 int evdns_nameserver_ip_add(const char *ip_as_string)
170 This wraps the above function by parsing a string as an IP
171 address and adds it as a nameserver. Returns non-zero on error
172 int evdns_resolve(const char *name, int flags, evdns_callback_type
174 callback, void *ptr)
175 Resolve a name. The name parameter should be a DNS name. The
176 flags parameter should be 0, or DNS_QUERY_NO_SEARCH which dis‐
177 ables searching for this query. (see defn of searching above).
178 The callback argument is a function which is called when this
180 query completes and ptr is an argument which is passed to that
181 callback function.
182 Returns non-zero on error
184 void evdns_search_clear()
186 Clears the list of search domains
187 void evdns_search_add(const char *domain)
189 Add a domain to the list of search domains
190 void evdns_search_ndots_set(int ndots)
192 Set the number of dots which, when found in a name, causes the
193 first query to be without any search domain.
194 int evdns_count_nameservers(void)
196 Return the number of configured nameservers (not necessarily the
197 number of running nameservers). This is useful for double-
198 checking whether our calls to the various nameserver configura‐
199 tion functions have been successful.
200 int evdns_clear_nameservers_and_suspend(void)
202 Remove all currently configured nameservers, and suspend all
203 pending resolves. Resolves will not necessarily be re-attempted
204 until evdns_resume() is called.
205 int evdns_resume(void)
207 Re-attempt resolves left in limbo after an earlier call to
208 evdns_clear_nameservers_and_suspend().
209 int evdns_config_windows_nameservers(void)
211 Attempt to configure a set of nameservers based on platform set‐
212 tings on a win32 host. Preferentially tries to use GetNetwork‐
213 Params; if that fails, looks in the registry. Returns 0 on suc‐
214 cess, nonzero on failure.
215 int evdns_resolv_conf_parse(int flags, const char *filename)
217 Parse a resolv.conf like file from the given filename.
218 See the man page for resolv.conf for the format of this file.
220 The flags argument determines what information is parsed from
221 this file:
222 DNS_OPTION_SEARCH domain, search and ndots options
223 DNS_OPTION_NAMESERVERS nameserver lines
224 DNS_OPTION_MISC timeout and attempts options
225 DNS_OPTIONS_ALL all of the above
226 The following directives are not parsed from the file:
228 sortlist, rotate, no-check-names, inet6, debug
229 Returns non-zero on error:
231 0 no errors
232 1 failed to open file
233 2 failed to stat file
234 3 file too large
235 4 out of memory
236 5 short read from file
237
239 Requests are kept in two queues. The first is the inflight queue. In this
240 queue requests have an allocated transaction id and nameserver. They
241 will soon be transmitted if they haven't already been.
242 The second is the waiting queue. The size of the inflight ring is limited
244 and all other requests wait in waiting queue for space. This bounds the
245 number of concurrent requests so that we don't flood the nameserver. Sev‐
246 eral algorithms require a full walk of the inflight queue and so bounding
247 its size keeps thing going nicely under huge (many thousands of requests)
248 loads.
249 If a nameserver loses too many requests it is considered down and we try
251 not to use it. After a while we send a probe to that nameserver (a lookup
252 for google.com) and, if it replies, we consider it working again. If the
253 nameserver fails a probe we wait longer to try again with the next probe.
254
256 event(3), gethostbyname(3), resolv.conf(5)
257
259 The evdns API was developed by Adam Langley on top of the libevent API.
260 The code was integrate into Tor by Nick Mathewson and finally put into
261 libevent itself by Niels Provos.
262
264 The evdns API and code was written by Adam Langley with significant con‐
265 tributions by Nick Mathewson.
266
268 This documentation is neither complete nor authoritative. If you are in
269 doubt about the usage of this API then check the source code to find out
270 how it works, write up the missing piece of documentation and send it to
271 me for inclusion in this man page.
272BSD October 7, 2006 BSD