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

FreeBSD Manual Pages

  
 
  

home | help
getdns_context(3)		    getdns		     getdns_context(3)

NAME
       getdns_context, getdns_context_create, getdns_context_create_with_mem-
       ory_functions, getdns_context_create_with_extended_memory_functions,
       getdns_context_destroy, getdns_context_get_api_information -- getdns
       context create and destroy routines

LIBRARY
       DNS Resolver library (libgetdns,	-lgetdns)

SYNOPSIS
       #include	<getdns.h>

       getdns_return_t
       getdns_context_create (getdns_context **	context,
	  int set_from_os)

       getdns_return_t
       getdns_context_create_with_memory_functions (getdns_context ** context,
	  int set_from_os,
	  void *(*malloc) (size_t),
	  void *(*realloc) (void *, size_t),
	  void (*free) (void *))

       getdns_return_t
       getdns_context_create_with_extended_memory_functions    (getdns_context
       **context,
	  int set_from_os,
	  void *userarg,
	  void *(*malloc) (void	*userarg, size_t),
	  void *(*realloc) (void *userarg, void	*, size_t),
	  void (*free) (void *userarg, void *))

       void
       getdns_context_destroy (getdns_context *context)

       getdns_dict *
       getdns_context_get_api_information (getdns_context *context)

DESCRIPTION
       Calls  to  getdns  functions require a DNS context, which is a group of
       API settings that affect	how DNS	calls are made.	For most applications,
       a default context is sufficient.

       To create a new DNS context, use	the function:
	  getdns_return_t  getdns_context_create  (getdns_context_t  *context,
	  bool set_from_os)

       The call	to getdns_context_create immediately returns  a	 context  that
       can  be	used with other	API calls; that	context	contains the API's de-
       fault values. Most applications will want set_from_os set to true.

       To clean	up the context,	including cleaning up all outstanding transac-
       tions that were called using this context, use the function:
	  void getdns_context_destroy (getdns_context_t	context)

       When  getdns_context_destroy()  returns,	the application	knows that all
       outstanding transactions	associated with	this context  will  have  been
       called;	callbacks  that	 had not been called before getdns_context_de-
       stroy() was called will be called with a	callback_type of  GETDNS_CALL-
       BACK_CANCEL.   getdns_context_destroy() returns after all of the	needed
       cleanup is done and callbacks are made.

       If you are using	getdns in a multi-threaded manner,  you	 are  then  of
       course using the	underlying OpenSSL library multi-threaded and the ver-
       sion of that library in use might have a	requirements  on  this	issue.
       You  may	 need  to provide one or two functions to allow	it to function
       properly. For example before you	call getdns_context_create()  you  may
       need   to   use	 the   openssl	functions  CRYPTO_set_id_callback  and
       CRYPTO_set_locking_callback to set up asynchronous operation (the   ap-
       plication  calls	 these	functions  once	 for initialisation).  Openssl
       1.0.0 or	later uses the CRYPTO_THREADID_set_callback function.

       context Used to return the pointer to an	opaque structure.  The	caller
	  passes  the  address	of  a  pointer (decl: getdns_context *context;
	  passed as &context) which will be populated as a result of returning
	  from	the function.  The result is a newly allocated and initialized
	  context (if there are	no  errors).   In  the	getdns_destroy_context
	  function  this  is  the  context whose associated memory will	be re-
	  leased.

       set_from_os If set_from_os is 0 then the	caller must provide forwarding
	  name	servers	if running in stub mode.  If set_from_os is 1 then the
	  system files are used	to initialize the  context.   /etc/resolv.conf
	  is used to populate forwarders when running as a stub	resolver (only
	  "nameserver" lines are recognized).  If set_from_os is 1  /etc/hosts
	  entries  are	preferred  before resorting to a DNS query.  Errors in
	  the system files will	not prevent the	context	form  being  construc-
	  ted.

       userarg	In  the	extended use case this argument	is passed unchanged to
	  each of the memory management	functions each time they are called.

       malloc The function that	will be	used for creating response dicts  (and
	  the  members within the response dicts).  By default the system mal-
	  loc is used.

       realloc The function that will be used for creating response dicts (and
	  the members within the response dicts).  By default the system real-
	  loc is used.

       free The	function that will be used for releasing storage for  response
	  dicts	 (and  the members within the response dicts).	By default the
	  system free is used.

DESCRIPTION (LONG)
       Many calls in the DNS API require a DNS context.	A DNS context contains
       the  information	that the API needs in order to process DNS calls, such
       as the locations	of upstream DNS	servers, DNSSEC	trust anchors, and  so
       on.  The	 internal structure of the DNS context is opaque, and might be
       different on each OS. When a context is passed to any function, it must
       be an allocated context;	the context must not be	NULL.

       A  typical  application	using  this  API doesn't need to know anything
       about contexts. Basically, the application creates a  default  context,
       uses  it	 in the	functions that require a context, and then deallocates
       it when done. Context manipulation is available for more	DNS-aware pro-
       grams, but is unlikely to be of interest	to applications	that just want
       the results of lookups for A, AAAA, SRV,	and PTR	records.

       It is expected that contexts in implementations of  the	API  will  not
       necessarily be thread-safe, but they will not be	thread-hostile.	A con-
       text should not be used by multiple threads: create a new  context  for
       use  on	a different thread. It is just fine for	an application to have
       many contexts, and some DNS-heavy applications will certainly  want  to
       have many even if the application uses a	single thread.

       When  the context is used in the	API for	the first time and set_from_os
       is 1, the API starts replacing some of the values with values from  the
       OS,  such  as  those  that  would  be  found  in	res_query(3), /etc/re-
       solv.conf, and so on, then proceeds with	the  new  function.  Some  ad-
       vanced users will not want the API to change the	values to the OS's de-
       faults; if set_from_os is 0, the	API will not do	 any  updates  to  the
       initial	values	based on changes in the	OS. For	example, this might be
       useful if the API is acting as a	stub resolver that is using a specific
       upstream	recursive resolver chosen by the application, not the one that
       might come back from DHCP.

RETURN VALUES
       Upon successful completion each of these	 functions  return  GETDNS_RE-
       TURN_GOOD , otherwise the following error values	are returned:

       GETDNS_RETURN_GENERIC_ERROR  memory allocation failed or	some other un-
       toward thing happened while initializing	the context

       GETDNS_RETURN_BAD_CONTEXT   if	the   context	pointer	  is   invalid
       (getdns_context_destroy)

       The  getdns_dict	returned by getdns_context_get_api_information must be
       destroyed by the	called and includes the	following name/value pairs:

       version_string
	      a	bindata	containing a printable string of the  version  of  the
	      DNS API implemented by this library

       implementation_string
	      a	 bindata  containing a printable string	set by the implementa-
	      tion

       resolution_type
	      an int equal to  GETDNS_RESOLUTION_RECURSING  or	GETDNS_RESOLU-
	      TION_STUB

       all_context
	      a	 getdns_dict  with names for all the types of context, feed it
	      to getdns_pretty_print_dict (3) for something easily readable

EXAMPLES
       TBD

FILES
       /etc/hosts
       /etc/resolv.conf

SEE ALSO
       libgetdns(3),  getdns_address(3),  getdns_address_sync(3),  getdns_con-
       text_set(3), getdns_context_set_context_update_callback(3), getdns_gen-
       eral(3),	  getdns_general_sync(3),   getdns_hostname(3),	  getdns_host-
       name_sync(3), getdns_service(3),	getdns_service_sync(3).

getdns 1.1.1			 December 2015		     getdns_context(3)

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | DESCRIPTION (LONG) | 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&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help