Annotation of embedaddon/libevent/evdns.3, revision 1.1.1.1
1.1 misho 1: .\"
2: .\" Copyright (c) 2006 Niels Provos <provos@citi.umich.edu>
3: .\" All rights reserved.
4: .\"
5: .\" Redistribution and use in source and binary forms, with or without
6: .\" modification, are permitted provided that the following conditions
7: .\" are met:
8: .\"
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
14: .\" 3. The name of the author may not be used to endorse or promote products
15: .\" derived from this software without specific prior written permission.
16: .\"
17: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
18: .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
19: .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
20: .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
21: .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
22: .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
23: .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
24: .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
25: .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
26: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27: .\"
28: .Dd October 7, 2006
29: .Dt EVDNS 3
30: .Os
31: .Sh NAME
32: .Nm evdns_init
33: .Nm evdns_shutdown
34: .Nm evdns_err_to_string
35: .Nm evdns_nameserver_add
36: .Nm evdns_count_nameservers
37: .Nm evdns_clear_nameservers_and_suspend
38: .Nm evdns_resume
39: .Nm evdns_nameserver_ip_add
40: .Nm evdns_resolve_ipv4
41: .Nm evdns_resolve_reverse
42: .Nm evdns_resolv_conf_parse
43: .Nm evdns_config_windows_nameservers
44: .Nm evdns_search_clear
45: .Nm evdns_search_add
46: .Nm evdns_search_ndots_set
47: .Nm evdns_set_log_fn
48: .Nd asynchronous functions for DNS resolution.
49: .Sh SYNOPSIS
50: .Fd #include <sys/time.h>
51: .Fd #include <event.h>
52: .Fd #include <evdns.h>
53: .Ft int
54: .Fn evdns_init
55: .Ft void
56: .Fn evdns_shutdown "int fail_requests"
57: .Ft "const char *"
58: .Fn evdns_err_to_string "int err"
59: .Ft int
60: .Fn evdns_nameserver_add "unsigned long int address"
61: .Ft int
62: .Fn evdns_count_nameservers
63: .Ft int
64: .Fn evdns_clear_nameservers_and_suspend
65: .Ft int
66: .Fn evdns_resume
67: .Ft int
68: .Fn evdns_nameserver_ip_add(const char *ip_as_string);
69: .Ft int
70: .Fn evdns_resolve_ipv4 "const char *name" "int flags" "evdns_callback_type callback" "void *ptr"
71: .Ft int
72: .Fn evdns_resolve_reverse "struct in_addr *in" "int flags" "evdns_callback_type callback" "void *ptr"
73: .Ft int
74: .Fn evdns_resolv_conf_parse "int flags" "const char *"
75: .Ft void
76: .Fn evdns_search_clear
77: .Ft void
78: .Fn evdns_search_add "const char *domain"
79: .Ft void
80: .Fn evdns_search_ndots_set "const int ndots"
81: .Ft void
82: .Fn evdns_set_log_fn "evdns_debug_log_fn_type fn"
83: .Ft int
84: .Fn evdns_config_windows_nameservers
85: .Sh DESCRIPTION
86: Welcome, gentle reader
87: .Pp
88: Async DNS lookups are really a whole lot harder than they should be,
89: mostly stemming from the fact that the libc resolver has never been
90: very good at them. Before you use this library you should see if libc
91: can do the job for you with the modern async call getaddrinfo_a
92: (see http://www.imperialviolet.org/page25.html#e498). Otherwise,
93: please continue.
94: .Pp
95: This code is based on libevent and you must call event_init before
96: any of the APIs in this file. You must also seed the OpenSSL random
97: source if you are using OpenSSL for ids (see below).
98: .Pp
99: This library is designed to be included and shipped with your source
100: code. You statically link with it. You should also test for the
101: existence of strtok_r and define HAVE_STRTOK_R if you have it.
102: .Pp
103: The DNS protocol requires a good source of id numbers and these
104: numbers should be unpredictable for spoofing reasons. There are
105: three methods for generating them here and you must define exactly
106: one of them. In increasing order of preference:
107: .Pp
108: .Bl -tag -width "DNS_USE_GETTIMEOFDAY_FOR_ID" -compact -offset indent
109: .It DNS_USE_GETTIMEOFDAY_FOR_ID
110: Using the bottom 16 bits of the usec result from gettimeofday. This
111: is a pretty poor solution but should work anywhere.
112: .It DNS_USE_CPU_CLOCK_FOR_ID
113: Using the bottom 16 bits of the nsec result from the CPU's time
114: counter. This is better, but may not work everywhere. Requires
115: POSIX realtime support and you'll need to link against -lrt on
116: glibc systems at least.
117: .It DNS_USE_OPENSSL_FOR_ID
118: Uses the OpenSSL RAND_bytes call to generate the data. You must
119: have seeded the pool before making any calls to this library.
120: .El
121: .Pp
122: The library keeps track of the state of nameservers and will avoid
123: them when they go down. Otherwise it will round robin between them.
124: .Pp
125: Quick start guide:
126: #include "evdns.h"
127: void callback(int result, char type, int count, int ttl,
128: void *addresses, void *arg);
129: evdns_resolv_conf_parse(DNS_OPTIONS_ALL, "/etc/resolv.conf");
130: evdns_resolve("www.hostname.com", 0, callback, NULL);
131: .Pp
132: When the lookup is complete the callback function is called. The
133: first argument will be one of the DNS_ERR_* defines in evdns.h.
134: Hopefully it will be DNS_ERR_NONE, in which case type will be
135: DNS_IPv4_A, count will be the number of IP addresses, ttl is the time
136: which the data can be cached for (in seconds), addresses will point
137: to an array of uint32_t's and arg will be whatever you passed to
138: evdns_resolve.
139: .Pp
140: Searching:
141: .Pp
142: In order for this library to be a good replacement for glibc's resolver it
143: supports searching. This involves setting a list of default domains, in
144: which names will be queried for. The number of dots in the query name
145: determines the order in which this list is used.
146: .Pp
147: Searching appears to be a single lookup from the point of view of the API,
148: although many DNS queries may be generated from a single call to
149: evdns_resolve. Searching can also drastically slow down the resolution
150: of names.
151: .Pp
152: To disable searching:
153: .Bl -enum -compact -offset indent
154: .It
155: Never set it up. If you never call
156: .Fn evdns_resolv_conf_parse,
157: .Fn evdns_init,
158: or
159: .Fn evdns_search_add
160: then no searching will occur.
161: .It
162: If you do call
163: .Fn evdns_resolv_conf_parse
164: then don't pass
165: .Va DNS_OPTION_SEARCH
166: (or
167: .Va DNS_OPTIONS_ALL,
168: which implies it).
169: .It
170: When calling
171: .Fn evdns_resolve,
172: pass the
173: .Va DNS_QUERY_NO_SEARCH
174: flag.
175: .El
176: .Pp
177: The order of searches depends on the number of dots in the name. If the
178: number is greater than the ndots setting then the names is first tried
179: globally. Otherwise each search domain is appended in turn.
180: .Pp
181: The ndots setting can either be set from a resolv.conf, or by calling
182: evdns_search_ndots_set.
183: .Pp
184: For example, with ndots set to 1 (the default) and a search domain list of
185: ["myhome.net"]:
186: Query: www
187: Order: www.myhome.net, www.
188: .Pp
189: Query: www.abc
190: Order: www.abc., www.abc.myhome.net
191: .Pp
192: .Sh API reference
193: .Pp
194: .Bl -tag -width 0123456
195: .It Ft int Fn evdns_init
196: Initializes support for non-blocking name resolution by calling
197: .Fn evdns_resolv_conf_parse
198: on UNIX and
199: .Fn evdns_config_windows_nameservers
200: on Windows.
201: .It Ft int Fn evdns_nameserver_add "unsigned long int address"
202: Add a nameserver. The address should be an IP address in
203: network byte order. The type of address is chosen so that
204: it matches in_addr.s_addr.
205: Returns non-zero on error.
206: .It Ft int Fn evdns_nameserver_ip_add "const char *ip_as_string"
207: This wraps the above function by parsing a string as an IP
208: address and adds it as a nameserver.
209: Returns non-zero on error
210: .It Ft int Fn evdns_resolve "const char *name" "int flags" "evdns_callback_type callback" "void *ptr"
211: Resolve a name. The name parameter should be a DNS name.
212: The flags parameter should be 0, or DNS_QUERY_NO_SEARCH
213: which disables searching for this query. (see defn of
214: searching above).
215: .Pp
216: The callback argument is a function which is called when
217: this query completes and ptr is an argument which is passed
218: to that callback function.
219: .Pp
220: Returns non-zero on error
221: .It Ft void Fn evdns_search_clear
222: Clears the list of search domains
223: .It Ft void Fn evdns_search_add "const char *domain"
224: Add a domain to the list of search domains
225: .It Ft void Fn evdns_search_ndots_set "int ndots"
226: Set the number of dots which, when found in a name, causes
227: the first query to be without any search domain.
228: .It Ft int Fn evdns_count_nameservers "void"
229: Return the number of configured nameservers (not necessarily the
230: number of running nameservers). This is useful for double-checking
231: whether our calls to the various nameserver configuration functions
232: have been successful.
233: .It Ft int Fn evdns_clear_nameservers_and_suspend "void"
234: Remove all currently configured nameservers, and suspend all pending
235: resolves. Resolves will not necessarily be re-attempted until
236: evdns_resume() is called.
237: .It Ft int Fn evdns_resume "void"
238: Re-attempt resolves left in limbo after an earlier call to
239: evdns_clear_nameservers_and_suspend().
240: .It Ft int Fn evdns_config_windows_nameservers "void"
241: Attempt to configure a set of nameservers based on platform settings on
242: a win32 host. Preferentially tries to use GetNetworkParams; if that fails,
243: looks in the registry. Returns 0 on success, nonzero on failure.
244: .It Ft int Fn evdns_resolv_conf_parse "int flags" "const char *filename"
245: Parse a resolv.conf like file from the given filename.
246: .Pp
247: See the man page for resolv.conf for the format of this file.
248: The flags argument determines what information is parsed from
249: this file:
250: .Bl -tag -width "DNS_OPTION_NAMESERVERS" -offset indent -compact -nested
251: .It DNS_OPTION_SEARCH
252: domain, search and ndots options
253: .It DNS_OPTION_NAMESERVERS
254: nameserver lines
255: .It DNS_OPTION_MISC
256: timeout and attempts options
257: .It DNS_OPTIONS_ALL
258: all of the above
259: .El
260: .Pp
261: The following directives are not parsed from the file:
262: sortlist, rotate, no-check-names, inet6, debug
263: .Pp
264: Returns non-zero on error:
265: .Bl -tag -width "0" -offset indent -compact -nested
266: .It 0
267: no errors
268: .It 1
269: failed to open file
270: .It 2
271: failed to stat file
272: .It 3
273: file too large
274: .It 4
275: out of memory
276: .It 5
277: short read from file
278: .El
279: .El
280: .Sh Internals:
281: Requests are kept in two queues. The first is the inflight queue. In
282: this queue requests have an allocated transaction id and nameserver.
283: They will soon be transmitted if they haven't already been.
284: .Pp
285: The second is the waiting queue. The size of the inflight ring is
286: limited and all other requests wait in waiting queue for space. This
287: bounds the number of concurrent requests so that we don't flood the
288: nameserver. Several algorithms require a full walk of the inflight
289: queue and so bounding its size keeps thing going nicely under huge
290: (many thousands of requests) loads.
291: .Pp
292: If a nameserver loses too many requests it is considered down and we
293: try not to use it. After a while we send a probe to that nameserver
294: (a lookup for google.com) and, if it replies, we consider it working
295: again. If the nameserver fails a probe we wait longer to try again
296: with the next probe.
297: .Sh SEE ALSO
298: .Xr event 3 ,
299: .Xr gethostbyname 3 ,
300: .Xr resolv.conf 5
301: .Sh HISTORY
302: The
303: .Nm evdns
304: API was developed by Adam Langley on top of the
305: .Nm libevent
306: API.
307: The code was integrate into
308: .Nm Tor
309: by Nick Mathewson and finally put into
310: .Nm libevent
311: itself by Niels Provos.
312: .Sh AUTHORS
313: The
314: .Nm evdns
315: API and code was written by Adam Langley with significant
316: contributions by Nick Mathewson.
317: .Sh BUGS
318: This documentation is neither complete nor authoritative.
319: If you are in doubt about the usage of this API then
320: check the source code to find out how it works, write
321: up the missing piece of documentation and send it to
322: me for inclusion in this man page.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to evdns.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libevent