Provided by: libgetdns-dev_1.6.0-3.1build3_amd64 bug

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).