Provided by: libgetdns-dev_0.9.0-1_amd64 
NAME
getdns_context_set_append_name, getdns_context_set_context_update_callback,
getdns_context_set_dns_root_servers, getdns_context_set_dns_transport,
getdns_context_set_dnssec_trust_anchors, getdns_context_set_dnssec_allowed_skew,
getdns_context_set_follow_redirects, getdns_context_set_limit_outstanding_queries,
getdns_context_set_namespaces, getdns_context_set_resolution_type,
getdns_context_set_suffix, getdns_context_set_timeout, -- getdns context manipulation
routines
LIBRARY
DNS Resolver library (libgetdns, -lgetdns)
SYNOPSIS
#include <getdns.h>
getdns_return_t
getdns_context_set_append_name (getdns_context_t context,
getdns_append_name_t when_to_append)
getdns_return_t
getdns_context_set_context_update_callback (getdns_context_t context,
(*callback)(struct getdns_context *context, uint16_t changed_item))
getdns_return_t
getdns_context_set_dns_root_servers (getdns_context_t context,
getdns_list *root_addresses)
getdns_return_t
getdns_context_set_dns_transport (getdns_context_t context,
uint16_t transport)
getdns_return_t
getdns_contet_set_dnssec_allowed_skew (getdns_context *context,
uint32_t skew_seconds)
getdns_return_t
getdns_contet_set_dnssec_trust_anchors (getdns_context *context,
getdns_list *trust_anchors)
getdns_return_t
getdns_context_set_follow_redirects (getdns_context_t context,
getdns_redirects_t followredir)
getdns_return_t
getdns_context_set_limit_outstanding_queries (getdns_context_t context,
uint16_t limit)
getdns_return_t
getdns_context_set_namespaces (getdns_context_t context,
size_t namespace_count,
uint16_t *namespaces)
getdns_return_t
getdns_context_set_resolution_type (getdns_context_t context,
uint16_t restype)
getdns_return_t
getdns_context_set_suffix (getdns_context *context,
getdns_list *suffixes)
getdns_return_t
getdns_context_set_timeout (getdns_context_t context,
uint16_t timeout)
DESCRIPTION
These functions are used to manipulate a previously allocated and initialized context, see
getdns_context (3) for more details on the functions used to allocate, initialized and
destroy contexts and for a more detailed discussion of the getdns_context in general.
getdns_context_set_append_name Specifies whether to append a suffix supplied via
getdns_context_set_suffix (3) to the query string before the API starts resolving a name.
getdns_context_set_context_update_callback sets a function that will be called if changes
to the system files (for example /etc/resolv.conf and /etc/hosts).
getdns_context_set_dns_transport specifies the transport used for DNS lookups, the default
is to use UDP and fall back to TCP as needed.
getdns_context_set_dnssec_trust_anchors allows the caller to specify trust anchors as
alternatives to the default trust anchors
getdns_context_set_dnssec_allowed_skew set the number of seconds skew allowed in either
direction when checking an RRSIGs expiration and inception fields, the default is 0.
getdns_context_set_limit_outstanding_queries specifies the maximum number of outstanding
DNS queries, the API will queue queries over this limit until current queries are answers
and will then automatically issue the queries on the queue.
getdns_context_set_dns_root_servers provides an alternate set of addresses to use to look
up the top level domains. The default (if this function is not called) is the list of
IANA root servers (think of this as the root hints).
getdns_context_set_follow_redirects specifies whether or not DNS queries follow redirects
(CNAME and DNAME), the default behavior is to follow redirects and return the eventual
target.
getdns_context_set_namespaces sets the namespaces to be used by the resolver, the default
is DNS and then local files. Future implementations will support netbios, mdns, and nis.
getdns_context_set_resolution_type specifies whether DNS queries are performed with non-
recursive lookups or as a stub resolver.
getdns_context_set_suffix Append suffixes to domain names prior to executing the lookup
based on getdns_context_set_append_name.
getdns_context_set_timeout specifies the number of milliseconds the API will wait for a
response.
context a previously allocated and initialized getdns_context
callback a callback function that will be called when changes are made to the system files
(/etc/resolv.conf and /etc/hosts) for contexts created with set_from_os = 1. When this
function is called the changed_item parameter indicates which item in the context has
changed.
root_addresses This is a list of getdns_dict types that each identify a single root server
to use to look up top level domains. Each dictionary includes two names, address_type
, a bindata containing the string "IPv4" or "IPv6" and address_data a bindata
containing the IP address.
transport may be one of GETDNS_CONTEXT_UDP_FIRST_AND_FALL_BACK_TO_TCP,
GETDNS_CONTEXT_UDP_ONLY, GETDNS_CONTEXT_TCP_ONLY,
GETDNS_CONTEXT_TCP_ONLY_KEEP_CONNECTIONS_OPEN. If you need more information on what
each of these means reread the mnemonic and take a guess ;)
followredir If set to GETDNS_REDIRECTS_FOLLOW (the default) then the eventual target of
the redirect is returned. If set to GETDNS_REDIRECTS_DO_NOT_FOLLOW then the CNAME or
DNAME is returned and NOT the eventual target.
limit the maximum number of concurrent outstanding (unanswered) DNS queries, if exceeded
the API will queue queries and issue them as the number of outstanding queries drops.
A value of 0 indicates that there is no limit.
namespaces The namespaces array contains an ordered list of namespaces that will be
queried. Important: this context setting is ignored for the getdns_general and
getdns_general_sync functions; it is used for the other functions. The values are
GETDNS_CONTEXT_NAMESPACE_DNS, GETDNS_CONTEXT_NAMESPACE_LOCALNAMES,
GETDNS_CONTEXT_NAMESPACE_NETBIOS, GETDNS_CONTEXT_NAMESPACE_MDNS, and
GETDNS_CONTEXT_NAMESPACE_NIS. When a normal lookup is done, the API does the lookups in
the order given and stops when it gets the first result; a different method with the
same result would be to run the queries in parallel and return when it gets the first
result. Because lookups might be done over different mechanisms because of the
different namespaces, there can be information leakage that is similar to that seen
with getaddrinfo(). The default is determined by the OS.
restype can be set to either GETDNS_CONTEXT_RECURSIVE (the default) or GETDNS_CONTEXT_STUB
(requires that forwarders be specified by the caller).
seconds_skew the number of seconds skew allowed in either direction when checking an
RRSIGs expiration and inception fields.
suffixes A list of bindatas that are strings that are to be appended based on
getdns_context_set_append_name. The values here follow the rules in section 2.1 of RFC
4343 to allow non-ASCII octets and special characters in labels.
timeout the number of milliseconds the API will wait for a response, after which the
callback will be invoked (or the synchronous function will return) with a timeout
error.
trust_anchors list of bindatas that are the DNSSEC trust anchors expressed as RDATA from
the DNSKEY resource records, the default are supplied by the IANA root.
when_to_append The value is
• GETDNS_APPEND_NAME_ALWAYS,
• GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,
• GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, or
• GETDNS_APPEND_NAME_NEVER.
RETURN VALUES
Upon successful completion the functions return GETDNS_RETURN_GOOD , otherwise the
following error values are returned:
GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid
GETDNS_RETURN_CONTEXT_UPDATE_FAIL if there was a problem updating the context
EXAMPLES
TBD
FILES
/etc/hosts
/etc/resolv.conf
SEE ALSO
libgetdns(3), getdns_address(3), getdns_address_sync(3), getdns_context(3),
getdns_general(3), getdns_general_sync(3), getdns_hostname(3), getdns_hostname_sync(3),
getdns_service(3), getdns_service_sync(3).