getdns_context_set(3) getdns getdns_context_set(3)NAME
getdns_context_set_append_name, getdns_context_set_context_update_call‐
back, getdns_context_set_dns_root_servers, getdns_con‐
text_set_dns_transport, getdns_context_set_dnssec_trust_anchors,
getdns_context_set_dnssec_allowed_skew, getdns_context_set_follow_redi‐
rects, getdns_context_set_limit_outstanding_queries, getdns_con‐
text_set_namespaces, getdns_context_set_resolution_type, getdns_con‐
text_set_suffix, getdns_context_set_timeout, -- getdns context manipu‐
lation 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 ini‐
tialized context, see getdns_context (3) for more details on the func‐
tions 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 num‐
ber 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 implementa‐
tions 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 exe‐
cuting 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 dic‐
tionary 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_CON‐
TEXT_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_REDI‐
RECTS_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_NET‐
BIOS, GETDNS_CONTEXT_NAMESPACE_MDNS, and GETDNS_CONTEXT_NAMES‐
PACE_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 spe‐
cial 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 func‐
tion 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 ALSOlibgetdns(3), getdns_address(3), getdns_address_sync(3), getdns_con‐
text(3), getdns_general(3), getdns_general_sync(3), getdns_hostname(3),
getdns_hostname_sync(3), getdns_service(3), getdns_service_sync(3).
getdns 0.9.0 December 2015 getdns_context_set(3)
