1 .TH "event2/dns.h" 3 "Tue Jan 27 2015" "libevent" \" -*- nroff -*-
7 Welcome, gentle reader\&.
12 \fC#include <event2/util\&.h>\fP
19 .RI "#define \fBDNS_ERR_CANCEL\fP 69"
21 .RI "\fIThe request was canceled via a call to evdns_cancel_request\&. \fP"
23 .RI "#define \fBDNS_ERR_FORMAT\fP 1"
25 .RI "\fIThe name server was unable to interpret the query\&. \fP"
27 .RI "#define \fBDNS_ERR_NODATA\fP 70"
29 .RI "\fIThere were no answers and no error condition in the DNS packet\&. \fP"
31 .RI "#define \fBDNS_ERR_NONE\fP 0"
33 .RI "\fIError codes 0-5 are as described in RFC 1035\&. \fP"
35 .RI "#define \fBDNS_ERR_NOTEXIST\fP 3"
37 .RI "\fIThe domain name does not exist\&. \fP"
39 .RI "#define \fBDNS_ERR_NOTIMPL\fP 4"
41 .RI "\fIThe name server does not support the requested kind of query\&. \fP"
43 .RI "#define \fBDNS_ERR_REFUSED\fP 5"
45 .RI "\fIThe name server refuses to reform the specified operation for policy reasons\&. \fP"
47 .RI "#define \fBDNS_ERR_SERVERFAILED\fP 2"
49 .RI "\fIThe name server was unable to process this query due to a problem with the name server\&. \fP"
51 .RI "#define \fBDNS_ERR_SHUTDOWN\fP 68"
53 .RI "\fIThe request was canceled because the DNS subsystem was shut down\&. \fP"
55 .RI "#define \fBDNS_ERR_TIMEOUT\fP 67"
57 .RI "\fICommunication with the server timed out\&. \fP"
59 .RI "#define \fBDNS_ERR_TRUNCATED\fP 65"
61 .RI "\fIThe reply was truncated or ill-formatted\&. \fP"
63 .RI "#define \fBDNS_ERR_UNKNOWN\fP 66"
65 .RI "\fIAn unknown error occurred\&. \fP"
67 .RI "#define \fBDNS_IPv4_A\fP 1"
70 .RI "#define \fBDNS_IPv6_AAAA\fP 3"
73 .RI "#define \fBDNS_NO_SEARCH\fP DNS_QUERY_NO_SEARCH"
76 .RI "#define \fBDNS_OPTION_HOSTSFILE\fP 8"
79 .RI "#define \fBDNS_OPTION_MISC\fP 4"
82 .RI "#define \fBDNS_OPTION_NAMESERVERS\fP 2"
85 .RI "#define \fBDNS_OPTION_SEARCH\fP 1"
88 .RI "#define \fBDNS_OPTIONS_ALL\fP 15"
91 .RI "#define \fBDNS_PTR\fP 2"
94 .RI "#define \fBDNS_QUERY_NO_SEARCH\fP 1"
97 .RI "#define \fBEVDNS_ADDITIONAL_SECTION\fP 2"
100 .RI "#define \fBEVDNS_ANSWER_SECTION\fP 0"
103 .RI "#define \fBEVDNS_AUTHORITY_SECTION\fP 1"
106 .RI "#define \fBEVDNS_CLASS_INET\fP 1"
109 .RI "#define \fBEVDNS_FLAGS_AA\fP 0x400"
112 .RI "#define \fBEVDNS_FLAGS_RD\fP 0x080"
115 .RI "#define \fBEVDNS_QTYPE_ALL\fP 255"
118 .RI "#define \fBEVDNS_QTYPE_AXFR\fP 252"
121 .RI "#define \fBEVDNS_TYPE_A\fP 1"
124 .RI "#define \fBEVDNS_TYPE_AAAA\fP 28"
127 .RI "#define \fBEVDNS_TYPE_CNAME\fP 5"
130 .RI "#define \fBEVDNS_TYPE_MX\fP 15"
133 .RI "#define \fBEVDNS_TYPE_NS\fP 2"
136 .RI "#define \fBEVDNS_TYPE_PTR\fP 12"
139 .RI "#define \fBEVDNS_TYPE_SOA\fP 6"
142 .RI "#define \fBEVDNS_TYPE_TXT\fP 16"
149 .RI "typedef void(* \fBevdns_callback_type\fP )(int result, char type, int count, int ttl, void *addresses, void *arg)"
151 .RI "\fIThe callback that contains the results from a lookup\&. \fP"
153 .RI "typedef void(* \fBevdns_debug_log_fn_type\fP )(int is_warning, const char *msg)"
155 .RI "\fIA callback that is invoked when a log message is generated\&. \fP"
157 .RI "typedef void(* \fBevdns_getaddrinfo_cb\fP )(int result, struct \fBevutil_addrinfo\fP *res, void *arg)"
159 .RI "\fICallback for evdns_getaddrinfo\&. \fP"
161 .RI "typedef void(* \fBevdns_request_callback_fn_type\fP )(struct evdns_server_request *, void *)"
163 .RI "\fIA callback to implement a DNS server\&. \fP"
169 .RI "struct evdns_server_port * \fBevdns_add_server_port_with_base\fP (struct \fBevent_base\fP *base, \fBevutil_socket_t\fP socket, int flags, \fBevdns_request_callback_fn_type\fP callback, void *user_data)"
171 .RI "\fICreate a new DNS server port\&. \fP"
173 .RI "int \fBevdns_base_clear_nameservers_and_suspend\fP (struct evdns_base *base)"
175 .RI "\fIRemove all configured nameservers, and suspend all pending resolves\&. \fP"
177 .RI "int \fBevdns_base_count_nameservers\fP (struct evdns_base *base)"
179 .RI "\fIGet the number of configured nameservers\&. \fP"
181 .RI "void \fBevdns_base_free\fP (struct evdns_base *base, int fail_requests)"
183 .RI "\fIShut down the asynchronous DNS resolver and terminate all active requests\&. \fP"
185 .RI "int \fBevdns_base_load_hosts\fP (struct evdns_base *base, const char *hosts_fname)"
187 .RI "\fILoad an /etc/hosts-style file from 'hosts_fname' into 'base'\&. \fP"
189 .RI "int \fBevdns_base_nameserver_add\fP (struct evdns_base *base, unsigned long int address)"
191 .RI "\fIAdd a nameserver\&. \fP"
193 .RI "int \fBevdns_base_nameserver_ip_add\fP (struct evdns_base *base, const char *ip_as_string)"
195 .RI "\fIAdd a nameserver by string address\&. \fP"
197 .RI "int \fBevdns_base_nameserver_sockaddr_add\fP (struct evdns_base *base, const struct sockaddr *sa, ev_socklen_t len, unsigned flags)"
199 .RI "\fIAdd a nameserver by sockaddr\&. \fP"
201 .RI "struct evdns_base * \fBevdns_base_new\fP (struct \fBevent_base\fP *\fBevent_base\fP, int initialize_nameservers)"
203 .RI "\fIInitialize the asynchronous DNS library\&. \fP"
205 .RI "int \fBevdns_base_resolv_conf_parse\fP (struct evdns_base *base, int flags, const char *const filename)"
207 .RI "\fIParse a resolv\&.conf file\&. \fP"
209 .RI "struct evdns_request * \fBevdns_base_resolve_ipv4\fP (struct evdns_base *base, const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)"
211 .RI "\fILookup an A record for a given name\&. \fP"
213 .RI "struct evdns_request * \fBevdns_base_resolve_ipv6\fP (struct evdns_base *base, const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)"
215 .RI "\fILookup an AAAA record for a given name\&. \fP"
217 .RI "struct evdns_request * \fBevdns_base_resolve_reverse\fP (struct evdns_base *base, const struct in_addr *in, int flags, \fBevdns_callback_type\fP callback, void *ptr)"
219 .RI "\fILookup a PTR record for a given IP address\&. \fP"
221 .RI "struct evdns_request * \fBevdns_base_resolve_reverse_ipv6\fP (struct evdns_base *base, const struct in6_addr *in, int flags, \fBevdns_callback_type\fP callback, void *ptr)"
223 .RI "\fILookup a PTR record for a given IPv6 address\&. \fP"
225 .RI "int \fBevdns_base_resume\fP (struct evdns_base *base)"
227 .RI "\fIResume normal operation and continue any suspended resolve requests\&. \fP"
229 .RI "void \fBevdns_base_search_add\fP (struct evdns_base *base, const char *domain)"
231 .RI "\fIAdd a domain to the list of search domains\&. \fP"
233 .RI "void \fBevdns_base_search_clear\fP (struct evdns_base *base)"
235 .RI "\fIObtain nameserver information using the Windows API\&. \fP"
237 .RI "void \fBevdns_base_search_ndots_set\fP (struct evdns_base *base, const int ndots)"
239 .RI "\fISet the 'ndots' parameter for searches\&. \fP"
241 .RI "int \fBevdns_base_set_option\fP (struct evdns_base *base, const char *option, const char *val)"
243 .RI "\fISet the value of a configuration option\&. \fP"
245 .RI "void \fBevdns_cancel_request\fP (struct evdns_base *base, struct evdns_request *req)"
247 .RI "\fICancels a pending DNS resolution request\&. \fP"
249 .RI "void \fBevdns_close_server_port\fP (struct evdns_server_port *port)"
251 .RI "\fIClose down a DNS server port, and free associated structures\&. \fP"
253 .RI "const char * \fBevdns_err_to_string\fP (int err)"
255 .RI "\fIConvert a DNS error code to a string\&. \fP"
257 .RI "struct evdns_getaddrinfo_request * \fBevdns_getaddrinfo\fP (struct evdns_base *dns_base, const char *nodename, const char *servname, const struct \fBevutil_addrinfo\fP *hints_in, \fBevdns_getaddrinfo_cb\fP cb, void *arg)"
259 .RI "\fIMake a non-blocking getaddrinfo request using the dns_base in 'dns_base'\&. \fP"
261 .RI "void \fBevdns_getaddrinfo_cancel\fP (struct evdns_getaddrinfo_request *req)"
264 .RI "int \fBevdns_server_request_add_a_reply\fP (struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl)"
267 .RI "int \fBevdns_server_request_add_aaaa_reply\fP (struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl)"
270 .RI "int \fBevdns_server_request_add_cname_reply\fP (struct evdns_server_request *req, const char *name, const char *cname, int ttl)"
273 .RI "int \fBevdns_server_request_add_ptr_reply\fP (struct evdns_server_request *req, struct in_addr *in, const char *inaddr_name, const char *hostname, int ttl)"
276 .RI "int \fBevdns_server_request_add_reply\fP (struct evdns_server_request *req, int section, const char *name, int type, int dns_class, int ttl, int datalen, int is_name, const char *data)"
279 .RI "int \fBevdns_server_request_drop\fP (struct evdns_server_request *req)"
281 .RI "\fIFree a DNS request without sending back a reply\&. \fP"
283 .RI "int \fBevdns_server_request_get_requesting_addr\fP (struct evdns_server_request *_req, struct sockaddr *sa, int addr_len)"
285 .RI "\fIGet the address that made a DNS request\&. \fP"
287 .RI "int \fBevdns_server_request_respond\fP (struct evdns_server_request *req, int err)"
289 .RI "\fISend back a response to a DNS request, and free the request structure\&. \fP"
291 .RI "void \fBevdns_server_request_set_flags\fP (struct evdns_server_request *req, int flags)"
293 .RI "\fISets some flags in a reply we're building\&. \fP"
295 .RI "void \fBevdns_set_log_fn\fP (\fBevdns_debug_log_fn_type\fP fn)"
297 .RI "\fISet the callback function to handle DNS log messages\&. \fP"
299 .RI "void \fBevdns_set_random_bytes_fn\fP (void(*fn)(char *, size_t))"
301 .RI "\fISet a callback used to generate random bytes\&. \fP"
303 .RI "void \fBevdns_set_transaction_id_fn\fP (ev_uint16_t(*fn)(void))"
305 .RI "\fISet a callback that will be invoked to generate transaction IDs\&. \fP"
307 .SH "Detailed Description"
309 Welcome, gentle reader\&.
311 Async DNS lookups are really a whole lot harder than they should be, mostly stemming from the fact that the libc resolver has never been very good at them\&. Before you use this library you should see if libc can do the job for you with the modern async call getaddrinfo_a (see http://www.imperialviolet.org/page25.html#e498)\&. Otherwise, please continue\&.
313 The library keeps track of the state of nameservers and will avoid them when they go down\&. Otherwise it will round robin between them\&.
315 Quick start guide: #include 'evdns\&.h' void callback(int result, char type, int count, int ttl, void *addresses, void *arg); evdns_resolv_conf_parse(DNS_OPTIONS_ALL, '/etc/resolv\&.conf'); evdns_resolve('www\&.hostname\&.com', 0, callback, NULL);
317 When the lookup is complete the callback function is called\&. The first argument will be one of the DNS_ERR_* defines in evdns\&.h\&. Hopefully it will be DNS_ERR_NONE, in which case type will be DNS_IPv4_A, count will be the number of IP addresses, ttl is the time which the data can be cached for (in seconds), addresses will point to an array of uint32_t's and arg will be whatever you passed to evdns_resolve\&.
321 In order for this library to be a good replacement for glibc's resolver it supports searching\&. This involves setting a list of default domains, in which names will be queried for\&. The number of dots in the query name determines the order in which this list is used\&.
323 Searching appears to be a single lookup from the point of view of the API, although many DNS queries may be generated from a single call to evdns_resolve\&. Searching can also drastically slow down the resolution of names\&.
325 To disable searching:
327 Never set it up\&. If you never call evdns_resolv_conf_parse or evdns_search_add then no searching will occur\&.
329 If you do call evdns_resolv_conf_parse then don't pass DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it)\&.
331 When calling evdns_resolve, pass the DNS_QUERY_NO_SEARCH flag\&.
334 The order of searches depends on the number of dots in the name\&. If the number is greater than the ndots setting then the names is first tried globally\&. Otherwise each search domain is appended in turn\&.
336 The ndots setting can either be set from a resolv\&.conf, or by calling evdns_search_ndots_set\&.
338 For example, with ndots set to 1 (the default) and a search domain list of ['myhome\&.net']: Query: www Order: www\&.myhome\&.net, www\&.
340 Query: www\&.abc Order: www\&.abc\&., www\&.abc\&.myhome\&.net
344 Requests are kept in two queues\&. The first is the inflight queue\&. In this queue requests have an allocated transaction id and nameserver\&. They will soon be transmitted if they haven't already been\&.
346 The second is the waiting queue\&. The size of the inflight ring is limited and all other requests wait in waiting queue for space\&. This bounds the number of concurrent requests so that we don't flood the nameserver\&. Several algorithms require a full walk of the inflight queue and so bounding its size keeps thing going nicely under huge (many thousands of requests) loads\&.
348 If a nameserver loses too many requests it is considered down and we try not to use it\&. After a while we send a probe to that nameserver (a lookup for google\&.com) and, if it replies, we consider it working again\&. If the nameserver fails a probe we wait longer to try again with the next probe\&.
349 .SH "Macro Definition Documentation"
351 .SS "#define DNS_ERR_NODATA 70"
354 There were no answers and no error condition in the DNS packet\&. This can happen when you ask for an address that exists, but a record type that doesn't\&.
355 .SS "#define DNS_ERR_NONE 0"
358 Error codes 0-5 are as described in RFC 1035\&.
359 .SS "#define DNS_ERR_SHUTDOWN 68"
362 The request was canceled because the DNS subsystem was shut down\&.
363 .SH "Typedef Documentation"
365 .SS "typedef void(* evdns_callback_type)(int result, char type, int count, int ttl, void *addresses, void *arg)"
368 The callback that contains the results from a lookup\&.
370 result is one of the DNS_ERR_* values (DNS_ERR_NONE for success)
372 type is either DNS_IPv4_A or DNS_PTR or DNS_IPv6_AAAA
374 count contains the number of addresses of form type
376 ttl is the number of seconds the resolution may be cached for\&.
378 addresses needs to be cast according to type\&. It will be an array of 4-byte sequences for ipv4, or an array of 16-byte sequences for ipv6, or a nul-terminated string for PTR\&.
381 .SS "typedef void(* evdns_debug_log_fn_type)(int is_warning, const char *msg)"
384 A callback that is invoked when a log message is generated\&.
388 \fIis_warning\fP indicates if the log message is a 'warning'
390 \fImsg\fP the content of the log message
394 .SS "typedef void(* evdns_getaddrinfo_cb)(int result, struct \fBevutil_addrinfo\fP *res, void *arg)"
397 Callback for evdns_getaddrinfo\&.
398 .SS "typedef void(* evdns_request_callback_fn_type)(struct evdns_server_request *, void *)"
401 A callback to implement a DNS server\&. The callback function receives a DNS request\&. It should then optionally add a number of answers to the reply using the evdns_server_request_add_*_reply functions, before calling either evdns_server_request_respond to send the reply back, or evdns_server_request_drop to decline to answer the request\&.
405 \fIreq\fP A newly received request
407 \fIuser_data\fP A pointer that was passed to \fBevdns_add_server_port_with_base()\fP\&.
411 .SH "Function Documentation"
413 .SS "struct evdns_server_port* evdns_add_server_port_with_base (struct \fBevent_base\fP *base, \fBevutil_socket_t\fPsocket, intflags, \fBevdns_request_callback_fn_type\fPcallback, void *user_data)"
416 Create a new DNS server port\&.
420 \fIbase\fP The event base to handle events for the server port\&.
422 \fIsocket\fP A UDP socket to accept DNS requests\&.
424 \fIflags\fP Always 0 for now\&.
426 \fIcallback\fP A function to invoke whenever we get a DNS request on the socket\&.
428 \fIuser_data\fP Data to pass to the callback\&.
433 an evdns_server_port structure for this server port\&.
437 .SS "int evdns_base_clear_nameservers_and_suspend (struct evdns_base *base)"
440 Remove all configured nameservers, and suspend all pending resolves\&. Resolves will not necessarily be re-attempted until \fBevdns_base_resume()\fP is called\&.
444 \fIbase\fP the evdns_base to which to apply this operation
449 0 if successful, or -1 if an error occurred
454 \fBevdns_base_resume()\fP
458 .SS "int evdns_base_count_nameservers (struct evdns_base *base)"
461 Get the number of configured nameservers\&. This returns the number of configured nameservers (not necessarily the number of running nameservers)\&. This is useful for double-checking whether our calls to the various nameserver configuration functions have been successful\&.
465 \fIbase\fP the evdns_base to which to apply this operation
470 the number of configured nameservers
475 \fBevdns_base_nameserver_add()\fP
479 .SS "void evdns_base_free (struct evdns_base *base, intfail_requests)"
482 Shut down the asynchronous DNS resolver and terminate all active requests\&. If the 'fail_requests' option is enabled, all active requests will return an empty result with the error flag set to DNS_ERR_SHUTDOWN\&. Otherwise, the requests will be silently discarded\&.
486 \fIevdns_base\fP the evdns base to free
488 \fIfail_requests\fP if zero, active requests will be aborted; if non-zero, active requests will return DNS_ERR_SHUTDOWN\&.
493 \fBevdns_base_new()\fP
497 .SS "int evdns_base_load_hosts (struct evdns_base *base, const char *hosts_fname)"
500 Load an /etc/hosts-style file from 'hosts_fname' into 'base'\&. If hosts_fname is NULL, add minimal entries for localhost, and nothing else\&.
502 Note that only evdns_getaddrinfo uses the /etc/hosts entries\&.
504 Return 0 on success, negative on failure\&.
505 .SS "int evdns_base_nameserver_add (struct evdns_base *base, unsigned long intaddress)"
508 Add a nameserver\&. The address should be an IPv4 address in network byte order\&. The type of address is chosen so that it matches in_addr\&.s_addr\&.
512 \fIbase\fP the evdns_base to which to add the name server
514 \fIaddress\fP an IP address in network byte order
519 0 if successful, or -1 if an error occurred
524 \fBevdns_base_nameserver_ip_add()\fP
528 .SS "int evdns_base_nameserver_ip_add (struct evdns_base *base, const char *ip_as_string)"
531 Add a nameserver by string address\&. This function parses a n IPv4 or IPv6 address from a string and adds it as a nameserver\&. It supports the following formats:
544 If no port is specified, it defaults to 53\&.
548 \fIbase\fP the evdns_base to which to apply this operation
553 0 if successful, or -1 if an error occurred
558 \fBevdns_base_nameserver_add()\fP
562 .SS "struct evdns_base* evdns_base_new (struct \fBevent_base\fP *event_base, intinitialize_nameservers)"
565 Initialize the asynchronous DNS library\&. This function initializes support for non-blocking name resolution by calling \fBevdns_resolv_conf_parse()\fP on UNIX and evdns_config_windows_nameservers() on Windows\&.
569 \fI\fBevent_base\fP\fP the event base to associate the dns client with
571 \fIinitialize_nameservers\fP 1 if resolve\&.conf processing should occur
576 evdns_base object if successful, or NULL if an error occurred\&.
581 \fBevdns_base_free()\fP
585 .SS "int evdns_base_resolv_conf_parse (struct evdns_base *base, intflags, const char *constfilename)"
588 Parse a resolv\&.conf file\&. The 'flags' parameter determines what information is parsed from the resolv\&.conf file\&. See the man page for resolv\&.conf for the format of this file\&.
590 The following directives are not parsed from the file: sortlist, rotate, no-check-names, inet6, debug\&.
592 If this function encounters an error, the possible return values are: 1 = failed to open file, 2 = failed to stat file, 3 = file too large, 4 = out of memory, 5 = short read from file, 6 = no nameservers listed in the file
596 \fIbase\fP the evdns_base to which to apply this operation
598 \fIflags\fP any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC| DNS_OPTION_HOSTSFILE|DNS_OPTIONS_ALL
600 \fIfilename\fP the path to the resolv\&.conf file
605 0 if successful, or various positive error codes if an error occurred (see above)
610 resolv\&.conf(3), evdns_config_windows_nameservers()
614 .SS "struct evdns_request* evdns_base_resolve_ipv4 (struct evdns_base *base, const char *name, intflags, \fBevdns_callback_type\fPcallback, void *ptr)"
617 Lookup an A record for a given name\&.
621 \fIbase\fP the evdns_base to which to apply this operation
623 \fIname\fP a DNS hostname
625 \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&.
627 \fIcallback\fP a callback function to invoke when the request is completed
629 \fIptr\fP an argument to pass to the callback function
634 an evdns_request object if successful, or NULL if an error occurred\&.
639 \fBevdns_resolve_ipv6()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP
643 .SS "struct evdns_request* evdns_base_resolve_ipv6 (struct evdns_base *base, const char *name, intflags, \fBevdns_callback_type\fPcallback, void *ptr)"
646 Lookup an AAAA record for a given name\&.
650 \fIbase\fP the evdns_base to which to apply this operation
652 \fIname\fP a DNS hostname
654 \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&.
656 \fIcallback\fP a callback function to invoke when the request is completed
658 \fIptr\fP an argument to pass to the callback function
663 an evdns_request object if successful, or NULL if an error occurred\&.
668 \fBevdns_resolve_ipv4()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP
672 .SS "struct evdns_request* evdns_base_resolve_reverse (struct evdns_base *base, const struct in_addr *in, intflags, \fBevdns_callback_type\fPcallback, void *ptr)"
675 Lookup a PTR record for a given IP address\&.
679 \fIbase\fP the evdns_base to which to apply this operation
681 \fIin\fP an IPv4 address
683 \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&.
685 \fIcallback\fP a callback function to invoke when the request is completed
687 \fIptr\fP an argument to pass to the callback function
692 an evdns_request object if successful, or NULL if an error occurred\&.
697 \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP
701 .SS "struct evdns_request* evdns_base_resolve_reverse_ipv6 (struct evdns_base *base, const struct in6_addr *in, intflags, \fBevdns_callback_type\fPcallback, void *ptr)"
704 Lookup a PTR record for a given IPv6 address\&.
708 \fIbase\fP the evdns_base to which to apply this operation
710 \fIin\fP an IPv6 address
712 \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&.
714 \fIcallback\fP a callback function to invoke when the request is completed
716 \fIptr\fP an argument to pass to the callback function
721 an evdns_request object if successful, or NULL if an error occurred\&.
726 \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP
730 .SS "int evdns_base_resume (struct evdns_base *base)"
733 Resume normal operation and continue any suspended resolve requests\&. Re-attempt resolves left in limbo after an earlier call to \fBevdns_base_clear_nameservers_and_suspend()\fP\&.
737 \fIbase\fP the evdns_base to which to apply this operation
742 0 if successful, or -1 if an error occurred
747 \fBevdns_base_clear_nameservers_and_suspend()\fP
751 .SS "void evdns_base_search_add (struct evdns_base *base, const char *domain)"
754 Add a domain to the list of search domains\&.
758 \fIdomain\fP the domain to be added to the search list
762 .SS "void evdns_base_search_clear (struct evdns_base *base)"
765 Obtain nameserver information using the Windows API\&. Attempt to configure a set of nameservers based on platform settings on a win32 host\&. Preferentially tries to use GetNetworkParams; if that fails, looks in the registry\&.
769 0 if successful, or -1 if an error occurred
774 \fBevdns_resolv_conf_parse()\fP Clear the list of search domains\&.
778 .SS "void evdns_base_search_ndots_set (struct evdns_base *base, const intndots)"
781 Set the 'ndots' parameter for searches\&. Sets the number of dots which, when found in a name, causes the first query to be without any search domain\&.
785 \fIndots\fP the new ndots parameter
789 .SS "int evdns_base_set_option (struct evdns_base *base, const char *option, const char *val)"
792 Set the value of a configuration option\&. The currently available configuration options are:
794 ndots, timeout, max-timeouts, max-inflight, attempts, randomize-case, bind-to, initial-probe-timeout, getaddrinfo-allow-skew\&.
796 In versions before Libevent 2\&.0\&.3-alpha, the option name needed to end with a colon\&.
800 \fIbase\fP the evdns_base to which to apply this operation
802 \fIoption\fP the name of the configuration option to be modified
804 \fIval\fP the value to be set
809 0 if successful, or -1 if an error occurred
813 .SS "void evdns_cancel_request (struct evdns_base *base, struct evdns_request *req)"
816 Cancels a pending DNS resolution request\&.
820 \fIbase\fP the evdns_base that was used to make the request
822 \fIreq\fP the evdns_request that was returned by calling a resolve function
827 \fBevdns_base_resolve_ipv4()\fP, \fBevdns_base_resolve_ipv6\fP, \fBevdns_base_resolve_reverse\fP
831 .SS "void evdns_close_server_port (struct evdns_server_port *port)"
834 Close down a DNS server port, and free associated structures\&.
835 .SS "const char* evdns_err_to_string (interr)"
838 Convert a DNS error code to a string\&.
842 \fIerr\fP the DNS error code
847 a string containing an explanation of the error code
851 .SS "struct evdns_getaddrinfo_request* evdns_getaddrinfo (struct evdns_base *dns_base, const char *nodename, const char *servname, const struct \fBevutil_addrinfo\fP *hints_in, \fBevdns_getaddrinfo_cb\fPcb, void *arg)"
854 Make a non-blocking getaddrinfo request using the dns_base in 'dns_base'\&. If we can answer the request immediately (with an error or not!), then we invoke cb immediately and return NULL\&. Otherwise we return an evdns_getaddrinfo_request and invoke cb later\&.
856 When the callback is invoked, we pass as its first argument the error code that getaddrinfo would return (or 0 for no error)\&. As its second argument, we pass the \fBevutil_addrinfo\fP structures we found (or NULL on error)\&. We pass 'arg' as the third argument\&.
861 The AI_V4MAPPED and AI_ALL flags are not currently implemented\&.
863 For ai_socktype, we only handle SOCKTYPE_STREAM, SOCKTYPE_UDP, and 0\&.
865 For ai_protocol, we only handle IPPROTO_TCP, IPPROTO_UDP, and 0\&.
868 .SS "void evdns_server_request_set_flags (struct evdns_server_request *req, intflags)"
871 Sets some flags in a reply we're building\&. Allows setting of the AA or RD flags
872 .SS "void evdns_set_log_fn (\fBevdns_debug_log_fn_type\fPfn)"
875 Set the callback function to handle DNS log messages\&. If this callback is not set, evdns log messages are handled with the regular Libevent logging system\&.
879 \fIfn\fP the callback to be invoked when a log message is generated
883 .SS "void evdns_set_random_bytes_fn (void(*)(char *, size_t)fn)"
886 Set a callback used to generate random bytes\&. By default, we use the same function as passed to evdns_set_transaction_id_fn to generate bytes two at a time\&. If a function is provided here, it's also used to generate transaction IDs\&.
888 NOTE: This function has no effect in Libevent 2\&.0\&.4-alpha and later, since Libevent now provides its own secure RNG\&.
889 .SS "void evdns_set_transaction_id_fn (ev_uint16_t(*)(void)fn)"
892 Set a callback that will be invoked to generate transaction IDs\&. By default, we pick transaction IDs based on the current clock time, which is bad for security\&.
896 \fIfn\fP the new callback, or NULL to use the default\&.
899 NOTE: This function has no effect in Libevent 2\&.0\&.4-alpha and later, since Libevent now provides its own secure RNG\&.
902 Generated automatically by Doxygen for libevent from the source code\&.