Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  in-
       ception 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 is-
       sue the queries on the queue.

       getdns_context_set_dns_root_servers provides an alternate  set  of  ad-
       dresses	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 re-
       solver, 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_NAME-
	  SPACE_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 ex-
	  pressed as RDATA from	the DNSKEY resource records, the  default  are
	  supplied by the IANA root.

       when_to_append The value	is

	  o  GETDNS_APPEND_NAME_ALWAYS,

	  o  GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,

	  o  GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, or

	  o  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_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 1.1.1			 December 2015		 getdns_context_set(3)

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | FILES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getdns_context_set_append_name&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help