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