Ubuntu Manpage: getdns_context, getdns_context_create, getdns_context_create_with_memory

Provided by: libgetdns-dev_1.6.0-3build1_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