Annotation of embedaddon/libevent/evdns.3, revision 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