Ubuntu Manpage: getdns_context, getdns_context_create, getdns_context_create_with_memory

Provided by: libgetdns-dev_1.6.0-3.1build3_amd64

NAME

       getdns_context, getdns_context_create, getdns_context_create_with_memory_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 default values. Most applications will want set_from_os set to true.

       To  clean  up the context, including cleaning up all outstanding transactions 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_destroy() was called will  be  called  with  a  callback_type  of  GETDNS_CALLBACK_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 version 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  application 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 released.

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

       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 malloc is used.

       realloc  The  function that will be used for creating response dicts (and the members within the response
          dicts).  By default the system realloc 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 programs, 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 context 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/resolv.conf, and so on, then proceeds with the new function. Some advanced users will not want the
API to change the values to the OS's defaults; 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_RETURN_GOOD , otherwise the following
       error values are returned:

       GETDNS_RETURN_GENERIC_ERROR memory  allocation  failed  or  some  other  untoward  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 implementation

       resolution_type
              an int equal to GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLUTION_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