.TH "event2/dns.h" 3 "libevent-2.1.13-stable" \" -*- nroff -*- .ad l .nh .SH NAME event2/dns.h \- Welcome, gentle reader\&. .SH SYNOPSIS .br .PP \fR#include \fP .br \fR#include \fP .br .SS "Macros" .in +1c .ti -1c .RI "#define \fBDNS_ERR_CANCEL\fP 69" .br .RI "The request was canceled via a call to evdns_cancel_request\&. " .ti -1c .RI "#define \fBDNS_ERR_FORMAT\fP 1" .br .RI "The name server was unable to interpret the query\&. " .ti -1c .RI "#define \fBDNS_ERR_NODATA\fP 70" .br .RI "There were no answers and no error condition in the DNS packet\&. " .ti -1c .RI "#define \fBDNS_ERR_NONE\fP 0" .br .RI "Error codes 0-5 are as described in RFC 1035\&. " .ti -1c .RI "#define \fBDNS_ERR_NOTEXIST\fP 3" .br .RI "The domain name does not exist\&. " .ti -1c .RI "#define \fBDNS_ERR_NOTIMPL\fP 4" .br .RI "The name server does not support the requested kind of query\&. " .ti -1c .RI "#define \fBDNS_ERR_REFUSED\fP 5" .br .RI "The name server refuses to reform the specified operation for policy reasons\&. " .ti -1c .RI "#define \fBDNS_ERR_SERVERFAILED\fP 2" .br .RI "The name server was unable to process this query due to a problem with the name server\&. " .ti -1c .RI "#define \fBDNS_ERR_SHUTDOWN\fP 68" .br .RI "The request was canceled because the DNS subsystem was shut down\&. " .ti -1c .RI "#define \fBDNS_ERR_TIMEOUT\fP 67" .br .RI "Communication with the server timed out\&. " .ti -1c .RI "#define \fBDNS_ERR_TRUNCATED\fP 65" .br .RI "The reply was truncated or ill-formatted\&. " .ti -1c .RI "#define \fBDNS_ERR_UNKNOWN\fP 66" .br .RI "An unknown error occurred\&. " .ti -1c .RI "#define \fBDNS_IPv4_A\fP 1" .br .ti -1c .RI "#define \fBDNS_IPv6_AAAA\fP 3" .br .ti -1c .RI "#define \fBDNS_NO_SEARCH\fP DNS_QUERY_NO_SEARCH" .br .ti -1c .RI "#define \fBDNS_OPTION_HOSTSFILE\fP 8" .br .ti -1c .RI "#define \fBDNS_OPTION_MISC\fP 4" .br .ti -1c .RI "#define \fBDNS_OPTION_NAMESERVERS\fP 2" .br .ti -1c .RI "#define \fBDNS_OPTION_NAMESERVERS_NO_DEFAULT\fP 16" .br .ti -1c .RI "#define \fBDNS_OPTION_SEARCH\fP 1" .br .ti -1c .RI "#define \fBDNS_OPTIONS_ALL\fP" .br .RI "All above: " .ti -1c .RI "#define \fBDNS_PTR\fP 2" .br .ti -1c .RI "#define \fBDNS_QUERY_NO_SEARCH\fP 1" .br .ti -1c .RI "#define \fBEVDNS_ADDITIONAL_SECTION\fP 2" .br .ti -1c .RI "#define \fBEVDNS_ANSWER_SECTION\fP 0" .br .ti -1c .RI "#define \fBEVDNS_AUTHORITY_SECTION\fP 1" .br .ti -1c .RI "#define \fBEVDNS_BASE_CONFIG_WINDOWS_NAMESERVERS_IMPLEMENTED\fP" .br .ti -1c .RI "#define \fBEVDNS_BASE_DISABLE_WHEN_INACTIVE\fP 0x8000" .br .RI "Flag for evdns_base_new: Do not prevent the libevent event loop from exiting when we have no active dns requests\&. " .ti -1c .RI "#define \fBEVDNS_BASE_INITIALIZE_NAMESERVERS\fP 1" .br .RI "Flag for evdns_base_new: process resolv\&.conf\&. " .ti -1c .RI "#define \fBEVDNS_BASE_NAMESERVERS_NO_DEFAULT\fP 0x10000" .br .RI "Flag for evdns_base_new: If EVDNS_BASE_INITIALIZE_NAMESERVERS isset, do not add default nameserver if there are no nameservers in resolv\&.conf\&. " .ti -1c .RI "#define \fBEVDNS_CLASS_INET\fP 1" .br .ti -1c .RI "#define \fBEVDNS_FLAGS_AA\fP 0x400" .br .ti -1c .RI "#define \fBEVDNS_FLAGS_RD\fP 0x080" .br .ti -1c .RI "#define \fBEVDNS_QTYPE_ALL\fP 255" .br .ti -1c .RI "#define \fBEVDNS_QTYPE_AXFR\fP 252" .br .ti -1c .RI "#define \fBEVDNS_TYPE_A\fP 1" .br .ti -1c .RI "#define \fBEVDNS_TYPE_AAAA\fP 28" .br .ti -1c .RI "#define \fBEVDNS_TYPE_CNAME\fP 5" .br .ti -1c .RI "#define \fBEVDNS_TYPE_MX\fP 15" .br .ti -1c .RI "#define \fBEVDNS_TYPE_NS\fP 2" .br .ti -1c .RI "#define \fBEVDNS_TYPE_PTR\fP 12" .br .ti -1c .RI "#define \fBEVDNS_TYPE_SOA\fP 6" .br .ti -1c .RI "#define \fBEVDNS_TYPE_TXT\fP 16" .br .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef void(* \fBevdns_callback_type\fP) (int result, char type, int count, int ttl, void *addresses, void *arg)" .br .RI "The callback that contains the results from a lookup\&. " .ti -1c .RI "typedef void(* \fBevdns_debug_log_fn_type\fP) (int is_warning, const char *msg)" .br .RI "A callback that is invoked when a log message is generated\&. " .ti -1c .RI "typedef void(* \fBevdns_getaddrinfo_cb\fP) (int result, struct \fBevutil_addrinfo\fP *res, void *arg)" .br .RI "Callback for evdns_getaddrinfo\&. " .ti -1c .RI "typedef void(* \fBevdns_request_callback_fn_type\fP) (struct evdns_server_request *, void *)" .br .RI "A callback to implement a DNS server\&. " .in -1c .SS "Functions" .in +1c .ti -1c .RI "EVENT2_EXPORT_SYMBOL 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)" .br .RI "Create a new DNS server port\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_clear_host_addresses\fP (struct evdns_base *base)" .br .RI "Remove all hosts entries that have been loaded into the \fBevent_base\fP via evdns_base_load_hosts or via event_base_resolv_conf_parse\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_clear_nameservers_and_suspend\fP (struct evdns_base *base)" .br .RI "Remove all configured nameservers, and suspend all pending resolves\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_config_windows_nameservers\fP (struct evdns_base *)" .br .RI "Obtain nameserver information using the Windows API\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_count_nameservers\fP (struct evdns_base *base)" .br .RI "Get the number of configured nameservers\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_free\fP (struct evdns_base *base, int fail_requests)" .br .RI "Shut down the asynchronous DNS resolver and terminate all active requests\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_get_nameserver_addr\fP (struct evdns_base *base, int idx, struct sockaddr *sa, ev_socklen_t len)" .br .RI "Retrieve the address of the 'idx'th configured nameserver\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_load_hosts\fP (struct evdns_base *base, const char *hosts_fname)" .br .RI "Load an /etc/hosts-style file from 'hosts_fname' into 'base'\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_nameserver_add\fP (struct evdns_base *base, unsigned long int address)" .br .RI "Add a nameserver\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_nameserver_ip_add\fP (struct evdns_base *base, const char *ip_as_string)" .br .RI "Add a nameserver by string address\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_nameserver_sockaddr_add\fP (struct evdns_base *base, const struct sockaddr *sa, ev_socklen_t len, unsigned flags)" .br .RI "Add a nameserver by sockaddr\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL struct evdns_base * \fBevdns_base_new\fP (struct event_base *event_base, int initialize_nameservers)" .br .RI "Initialize the asynchronous DNS library\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_resolv_conf_parse\fP (struct evdns_base *base, int flags, const char *const filename)" .br .RI "Parse a resolv\&.conf file\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL struct evdns_request * \fBevdns_base_resolve_ipv4\fP (struct evdns_base *base, const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)" .br .RI "Lookup an A record for a given name\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL struct evdns_request * \fBevdns_base_resolve_ipv6\fP (struct evdns_base *base, const char *name, int flags, \fBevdns_callback_type\fP callback, void *ptr)" .br .RI "Lookup an AAAA record for a given name\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL 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)" .br .RI "Lookup a PTR record for a given IP address\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL 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)" .br .RI "Lookup a PTR record for a given IPv6 address\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_resume\fP (struct evdns_base *base)" .br .RI "Resume normal operation and continue any suspended resolve requests\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_search_add\fP (struct evdns_base *base, const char *domain)" .br .RI "Add a domain to the list of search domains\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_search_clear\fP (struct evdns_base *base)" .br .RI "Clear the list of search domains\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_base_search_ndots_set\fP (struct evdns_base *base, const int ndots)" .br .RI "Set the 'ndots' parameter for searches\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_base_set_option\fP (struct evdns_base *base, const char *option, const char *val)" .br .RI "Set the value of a configuration option\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_cancel_request\fP (struct evdns_base *base, struct evdns_request *req)" .br .RI "Cancels a pending DNS resolution request\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_close_server_port\fP (struct evdns_server_port *port)" .br .RI "Close down a DNS server port, and free associated structures\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL const char * \fBevdns_err_to_string\fP (int err)" .br .RI "Convert a DNS error code to a string\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL 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)" .br .RI "Make a non-blocking getaddrinfo request using the dns_base in 'dns_base'\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_getaddrinfo_cancel\fP (struct evdns_getaddrinfo_request *req)" .br .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_add_a_reply\fP (struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl)" .br .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_add_aaaa_reply\fP (struct evdns_server_request *req, const char *name, int n, const void *addrs, int ttl)" .br .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_add_cname_reply\fP (struct evdns_server_request *req, const char *name, const char *cname, int ttl)" .br .ti -1c .RI "EVENT2_EXPORT_SYMBOL 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)" .br .ti -1c .RI "EVENT2_EXPORT_SYMBOL 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)" .br .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_drop\fP (struct evdns_server_request *req)" .br .RI "Free a DNS request without sending back a reply\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_get_requesting_addr\fP (struct evdns_server_request *req, struct sockaddr *sa, int addr_len)" .br .RI "Get the address that made a DNS request\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL int \fBevdns_server_request_respond\fP (struct evdns_server_request *req, int err)" .br .RI "Send back a response to a DNS request, and free the request structure\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_server_request_set_flags\fP (struct evdns_server_request *req, int flags)" .br .RI "Sets some flags in a reply we're building\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_set_log_fn\fP (\fBevdns_debug_log_fn_type\fP fn)" .br .RI "Set the callback function to handle DNS log messages\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_set_random_bytes_fn\fP (void(*fn)(char *, size_t))" .br .RI "Set a callback used to generate random bytes\&. " .ti -1c .RI "EVENT2_EXPORT_SYMBOL void \fBevdns_set_transaction_id_fn\fP (ev_uint16_t(*fn)(void))" .br .RI "Set a callback that will be invoked to generate transaction IDs\&. " .in -1c .SH "Detailed Description" .PP Welcome, gentle reader\&. 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\&. .PP The library keeps track of the state of nameservers and will avoid them when they go down\&. Otherwise it will round robin between them\&. .PP 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); .PP 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\&. .PP Searching: .PP 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\&. .PP 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\&. .PP To disable searching: .IP "1." 4 Never set it up\&. If you never call evdns_resolv_conf_parse or evdns_search_add then no searching will occur\&. .IP "2." 4 If you do call evdns_resolv_conf_parse then don't pass DNS_OPTION_SEARCH (or DNS_OPTIONS_ALL, which implies it)\&. .IP "3." 4 When calling evdns_resolve, pass the DNS_QUERY_NO_SEARCH flag\&. .PP .PP 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\&. .PP The ndots setting can either be set from a resolv\&.conf, or by calling evdns_search_ndots_set\&. .PP For example, with ndots set to 1 (the default) and a search domain list of ["myhome\&.net"]: Query: www Order: www\&.myhome\&.net, www\&. .PP Query: www\&.abc Order: www\&.abc\&., www\&.abc\&.myhome\&.net .PP Internals: .PP 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\&. .PP 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\&. .PP 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\&. .SH "Macro Definition Documentation" .PP .SS "#define DNS_ERR_NODATA 70" .PP 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\&. .SS "#define DNS_OPTIONS_ALL" \fBValue:\fP .nf ( \\ DNS_OPTION_SEARCH | \\ DNS_OPTION_NAMESERVERS | \\ DNS_OPTION_MISC | \\ DNS_OPTION_HOSTSFILE | \\ 0 \\ ) .PP .fi .PP All above: .IP "\(bu" 2 DNS_OPTION_SEARCH .IP "\(bu" 2 DNS_OPTION_NAMESERVERS .IP "\(bu" 2 DNS_OPTION_MISC .IP "\(bu" 2 DNS_OPTION_HOSTSFILE .PP .SS "#define EVDNS_BASE_NAMESERVERS_NO_DEFAULT 0x10000" .PP Flag for evdns_base_new: If EVDNS_BASE_INITIALIZE_NAMESERVERS isset, do not add default nameserver if there are no nameservers in resolv\&.conf\&. .PP \fBSee also\fP .RS 4 DNS_OPTION_NAMESERVERS_NO_DEFAULT .RE .PP .SH "Typedef Documentation" .PP .SS "typedef void(* evdns_callback_type) (int result, char type, int count, int ttl, void *addresses, void *arg)" .PP The callback that contains the results from a lookup\&. .IP "\(bu" 2 result is one of the DNS_ERR_* values (DNS_ERR_NONE for success) .IP "\(bu" 2 type is either DNS_IPv4_A or DNS_PTR or DNS_IPv6_AAAA .IP "\(bu" 2 count contains the number of addresses of form type .IP "\(bu" 2 ttl is the number of seconds the resolution may be cached for\&. .IP "\(bu" 2 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\&. .PP .SS "typedef void(* evdns_debug_log_fn_type) (int is_warning, const char *msg)" .PP A callback that is invoked when a log message is generated\&. .PP \fBParameters\fP .RS 4 \fIis_warning\fP indicates if the log message is a 'warning' .br \fImsg\fP the content of the log message .RE .PP .SS "typedef void(* evdns_request_callback_fn_type) (struct evdns_server_request *, void *)" .PP 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\&. .PP \fBParameters\fP .RS 4 \fIreq\fP A newly received request .br \fIuser_data\fP A pointer that was passed to \fBevdns_add_server_port_with_base()\fP\&. .RE .PP .SH "Function Documentation" .PP .SS "EVENT2_EXPORT_SYMBOL struct evdns_server_port * evdns_add_server_port_with_base (struct \fBevent_base\fP * base, \fBevutil_socket_t\fP socket, int flags, \fBevdns_request_callback_fn_type\fP callback, void * user_data)" .PP Create a new DNS server port\&. .PP \fBParameters\fP .RS 4 \fIbase\fP The event base to handle events for the server port\&. .br \fIsocket\fP A UDP socket to accept DNS requests\&. .br \fIflags\fP Always 0 for now\&. .br \fIcallback\fP A function to invoke whenever we get a DNS request on the socket\&. .br \fIuser_data\fP Data to pass to the callback\&. .RE .PP \fBReturns\fP .RS 4 an evdns_server_port structure for this server port or NULL if an error occurred\&. .RE .PP .SS "EVENT2_EXPORT_SYMBOL void evdns_base_clear_host_addresses (struct evdns_base * base)" .PP Remove all hosts entries that have been loaded into the \fBevent_base\fP via evdns_base_load_hosts or via event_base_resolv_conf_parse\&. .PP \fBParameters\fP .RS 4 \fIevdns_base\fP the evdns base to remove outdated host addresses from .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evdns_base_clear_nameservers_and_suspend (struct evdns_base * base)" .PP Remove all configured nameservers, and suspend all pending resolves\&. Resolves will not necessarily be re-attempted until \fBevdns_base_resume()\fP is called\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .RE .PP \fBReturns\fP .RS 4 0 if successful, or -1 if an error occurred .RE .PP \fBSee also\fP .RS 4 \fBevdns_base_resume()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evdns_base_config_windows_nameservers (struct evdns_base * )" .PP 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\&. .PP \fBReturns\fP .RS 4 0 if successful, or -1 if an error occurred .RE .PP \fBSee also\fP .RS 4 \fBevdns_resolv_conf_parse()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evdns_base_count_nameservers (struct evdns_base * base)" .PP 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\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .RE .PP \fBReturns\fP .RS 4 the number of configured nameservers .RE .PP \fBSee also\fP .RS 4 \fBevdns_base_nameserver_add()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL void evdns_base_free (struct evdns_base * base, int fail_requests)" .PP 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\&. .PP \fBParameters\fP .RS 4 \fIevdns_base\fP the evdns base to free .br \fIfail_requests\fP if zero, active requests will be aborted; if non-zero, active requests will return DNS_ERR_SHUTDOWN\&. .RE .PP \fBSee also\fP .RS 4 \fBevdns_base_new()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evdns_base_get_nameserver_addr (struct evdns_base * base, int idx, struct sockaddr * sa, ev_socklen_t len)" .PP Retrieve the address of the 'idx'th configured nameserver\&. .PP \fBParameters\fP .RS 4 \fIbase\fP The evdns_base to examine\&. .br \fIidx\fP The index of the nameserver to get the address of\&. .br \fIsa\fP A location to receive the server's address\&. .br \fIlen\fP The number of bytes available at sa\&. .RE .PP \fBReturns\fP .RS 4 the number of bytes written into sa on success\&. On failure, returns -1 if idx is greater than the number of configured nameservers, or a value greater than 'len' if len was not high enough\&. .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evdns_base_load_hosts (struct evdns_base * base, const char * hosts_fname)" .PP Load an /etc/hosts-style file from 'hosts_fname' into 'base'\&. If hosts_fname is NULL, add minimal entries for localhost, and nothing else\&. .PP Note that only evdns_getaddrinfo uses the /etc/hosts entries\&. .PP This function does not replace previously loaded hosts entries; to do that, call evdns_base_clear_host_addresses first\&. .PP Return 0 on success, negative on failure\&. .SS "EVENT2_EXPORT_SYMBOL int evdns_base_nameserver_add (struct evdns_base * base, unsigned long int address)" .PP 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\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to add the name server .br \fIaddress\fP an IP address in network byte order .RE .PP \fBReturns\fP .RS 4 0 if successful, or -1 if an error occurred .RE .PP \fBSee also\fP .RS 4 \fBevdns_base_nameserver_ip_add()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evdns_base_nameserver_ip_add (struct evdns_base * base, const char * ip_as_string)" .PP 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: .IP "\(bu" 2 [IPv6Address]:port .IP "\(bu" 2 [IPv6Address] .IP "\(bu" 2 IPv6Address .IP "\(bu" 2 IPv4Address:port .IP "\(bu" 2 IPv4Address .PP .PP If no port is specified, it defaults to 53\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .RE .PP \fBReturns\fP .RS 4 0 if successful, or -1 if an error occurred .RE .PP \fBSee also\fP .RS 4 \fBevdns_base_nameserver_add()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL struct evdns_base * evdns_base_new (struct \fBevent_base\fP * event_base, int initialize_nameservers)" .PP 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\&. .PP \fBParameters\fP .RS 4 \fIevent_base\fP the event base to associate the dns client with .br \fIflags\fP any of EVDNS_BASE_INITIALIZE_NAMESERVERS| EVDNS_BASE_DISABLE_WHEN_INACTIVE|EVDNS_BASE_NAMESERVERS_NO_DEFAULT .RE .PP \fBReturns\fP .RS 4 evdns_base object if successful, or NULL if an error occurred\&. .RE .PP \fBSee also\fP .RS 4 \fBevdns_base_free()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evdns_base_resolv_conf_parse (struct evdns_base * base, int flags, const char *const filename)" .PP 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\&. .PP The following directives are not parsed from the file: sortlist, rotate, no-check-names, inet6, debug\&. .PP 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 .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .br \fIflags\fP any of DNS_OPTION_NAMESERVERS|DNS_OPTION_SEARCH|DNS_OPTION_MISC| DNS_OPTION_HOSTSFILE|DNS_OPTIONS_ALL|DNS_OPTION_NAMESERVERS_NO_DEFAULT .br \fIfilename\fP the path to the resolv\&.conf file .RE .PP \fBReturns\fP .RS 4 0 if successful, or various positive error codes if an error occurred (see above) .RE .PP \fBSee also\fP .RS 4 resolv\&.conf(3), evdns_config_windows_nameservers() .RE .PP .SS "EVENT2_EXPORT_SYMBOL struct evdns_request * evdns_base_resolve_ipv4 (struct evdns_base * base, const char * name, int flags, \fBevdns_callback_type\fP callback, void * ptr)" .PP Lookup an A record for a given name\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .br \fIname\fP a DNS hostname .br \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. .br \fIcallback\fP a callback function to invoke when the request is completed .br \fIptr\fP an argument to pass to the callback function .RE .PP \fBReturns\fP .RS 4 an evdns_request object if successful, or NULL if an error occurred\&. .RE .PP \fBSee also\fP .RS 4 \fBevdns_resolve_ipv6()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL struct evdns_request * evdns_base_resolve_ipv6 (struct evdns_base * base, const char * name, int flags, \fBevdns_callback_type\fP callback, void * ptr)" .PP Lookup an AAAA record for a given name\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .br \fIname\fP a DNS hostname .br \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. .br \fIcallback\fP a callback function to invoke when the request is completed .br \fIptr\fP an argument to pass to the callback function .RE .PP \fBReturns\fP .RS 4 an evdns_request object if successful, or NULL if an error occurred\&. .RE .PP \fBSee also\fP .RS 4 \fBevdns_resolve_ipv4()\fP, \fBevdns_resolve_reverse()\fP, \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL struct evdns_request * evdns_base_resolve_reverse (struct evdns_base * base, const struct in_addr * in, int flags, \fBevdns_callback_type\fP callback, void * ptr)" .PP Lookup a PTR record for a given IP address\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .br \fIin\fP an IPv4 address .br \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. .br \fIcallback\fP a callback function to invoke when the request is completed .br \fIptr\fP an argument to pass to the callback function .RE .PP \fBReturns\fP .RS 4 an evdns_request object if successful, or NULL if an error occurred\&. .RE .PP \fBSee also\fP .RS 4 \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL struct evdns_request * evdns_base_resolve_reverse_ipv6 (struct evdns_base * base, const struct in6_addr * in, int flags, \fBevdns_callback_type\fP callback, void * ptr)" .PP Lookup a PTR record for a given IPv6 address\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .br \fIin\fP an IPv6 address .br \fIflags\fP either 0, or DNS_QUERY_NO_SEARCH to disable searching for this query\&. .br \fIcallback\fP a callback function to invoke when the request is completed .br \fIptr\fP an argument to pass to the callback function .RE .PP \fBReturns\fP .RS 4 an evdns_request object if successful, or NULL if an error occurred\&. .RE .PP \fBSee also\fP .RS 4 \fBevdns_resolve_reverse_ipv6()\fP, \fBevdns_cancel_request()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evdns_base_resume (struct evdns_base * base)" .PP 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\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .RE .PP \fBReturns\fP .RS 4 0 if successful, or -1 if an error occurred .RE .PP \fBSee also\fP .RS 4 \fBevdns_base_clear_nameservers_and_suspend()\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL void evdns_base_search_add (struct evdns_base * base, const char * domain)" .PP Add a domain to the list of search domains\&. .PP \fBParameters\fP .RS 4 \fIdomain\fP the domain to be added to the search list .RE .PP .SS "EVENT2_EXPORT_SYMBOL void evdns_base_search_ndots_set (struct evdns_base * base, const int ndots)" .PP 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\&. .PP \fBParameters\fP .RS 4 \fIndots\fP the new ndots parameter .RE .PP .SS "EVENT2_EXPORT_SYMBOL int evdns_base_set_option (struct evdns_base * base, const char * option, const char * val)" .PP Set the value of a configuration option\&. The currently available configuration options are: .PP ndots, timeout, max-timeouts, max-inflight, attempts, randomize-case, bind-to, initial-probe-timeout, getaddrinfo-allow-skew, so-rcvbuf, so-sndbuf\&. .PP In versions before Libevent 2\&.0\&.3-alpha, the option name needed to end with a colon\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base to which to apply this operation .br \fIoption\fP the name of the configuration option to be modified .br \fIval\fP the value to be set .RE .PP \fBReturns\fP .RS 4 0 if successful, or -1 if an error occurred .RE .PP .SS "EVENT2_EXPORT_SYMBOL void evdns_cancel_request (struct evdns_base * base, struct evdns_request * req)" .PP Cancels a pending DNS resolution request\&. .PP \fBParameters\fP .RS 4 \fIbase\fP the evdns_base that was used to make the request .br \fIreq\fP the evdns_request that was returned by calling a resolve function .RE .PP \fBSee also\fP .RS 4 \fBevdns_base_resolve_ipv4()\fP, \fBevdns_base_resolve_ipv6\fP, \fBevdns_base_resolve_reverse\fP .RE .PP .SS "EVENT2_EXPORT_SYMBOL const char * evdns_err_to_string (int err)" .PP Convert a DNS error code to a string\&. .PP \fBParameters\fP .RS 4 \fIerr\fP the DNS error code .RE .PP \fBReturns\fP .RS 4 a string containing an explanation of the error code .RE .PP .SS "EVENT2_EXPORT_SYMBOL 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\fP cb, void * arg)" .PP 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\&. .PP 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\&. .PP Limitations: .PP .IP "\(bu" 2 The AI_V4MAPPED and AI_ALL flags are not currently implemented\&. .IP "\(bu" 2 For ai_socktype, we only handle SOCKTYPE_STREAM, SOCKTYPE_UDP, and 0\&. .IP "\(bu" 2 For ai_protocol, we only handle IPPROTO_TCP, IPPROTO_UDP, and 0\&. .PP .SS "EVENT2_EXPORT_SYMBOL void evdns_server_request_set_flags (struct evdns_server_request * req, int flags)" .PP Sets some flags in a reply we're building\&. Allows setting of the AA or RD flags .SS "EVENT2_EXPORT_SYMBOL void evdns_set_log_fn (\fBevdns_debug_log_fn_type\fP fn)" .PP 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\&. .PP \fBParameters\fP .RS 4 \fIfn\fP the callback to be invoked when a log message is generated .RE .PP .SS "EVENT2_EXPORT_SYMBOL void evdns_set_random_bytes_fn (void(* fn )(char *, size_t))" .PP 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\&. .PP NOTE: This function has no effect in Libevent 2\&.0\&.4-alpha and later, since Libevent now provides its own secure RNG\&. .SS "EVENT2_EXPORT_SYMBOL void evdns_set_transaction_id_fn (ev_uint16_t(* fn )(void))" .PP 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\&. .PP \fBParameters\fP .RS 4 \fIfn\fP the new callback, or NULL to use the default\&. .RE .PP NOTE: This function has no effect in Libevent 2\&.0\&.4-alpha and later, since Libevent now provides its own secure RNG\&. .SH "Author" .PP Generated automatically by Doxygen for libevent-2\&.1\&.13-stable from the source code\&.