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
default 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_con‐
text_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.
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 con‐
structed.
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/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 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 ALSOlibgetdns(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 0.9.0 December 2015 getdns_context(3)
