1
2getdns_context(3)                   getdns                   getdns_context(3)
3
4
5

NAME

7       getdns_context, getdns_context_create, getdns_context_create_with_mem‐
8       ory_functions, getdns_context_create_with_extended_memory_functions,
9       getdns_context_destroy, getdns_context_get_api_information -- getdns
10       context create and destroy routines
11
12

LIBRARY

14       DNS Resolver library (libgetdns, -lgetdns)
15
16

SYNOPSIS

18       #include <getdns.h>
19
20       getdns_return_t
21       getdns_context_create (getdns_context ** context,
22          int set_from_os)
23
24       getdns_return_t
25       getdns_context_create_with_memory_functions (getdns_context ** context,
26          int set_from_os,
27          void *(*malloc) (size_t),
28          void *(*realloc) (void *, size_t),
29          void (*free) (void *))
30
31       getdns_return_t
32       getdns_context_create_with_extended_memory_functions    (getdns_context
33       **context,
34          int set_from_os,
35          void *userarg,
36          void *(*malloc) (void *userarg, size_t),
37          void *(*realloc) (void *userarg, void *, size_t),
38          void (*free) (void *userarg, void *))
39
40       void
41       getdns_context_destroy (getdns_context *context)
42
43       getdns_dict *
44       getdns_context_get_api_information (getdns_context *context)
45
46

DESCRIPTION

48       Calls  to  getdns  functions require a DNS context, which is a group of
49       API settings that affect how DNS calls are made. For most applications,
50       a default context is sufficient.
51
52
53       To create a new DNS context, use the function:
54          getdns_return_t  getdns_context_create  (getdns_context_t  *context,
55          bool set_from_os)
56
57
58       The call to getdns_context_create immediately returns  a  context  that
59       can  be  used with other API calls; that context contains the API's de‐
60       fault values. Most applications will want set_from_os set to true.
61
62
63       To clean up the context, including cleaning up all outstanding transac‐
64       tions that were called using this context, use the function:
65          void getdns_context_destroy (getdns_context_t context)
66
67
68       When  getdns_context_destroy()  returns, the application knows that all
69       outstanding transactions associated with this context  will  have  been
70       called;  callbacks  that  had not been called before getdns_context_de‐
71       stroy() was called will be called with a callback_type of  GETDNS_CALL‐
72       BACK_CANCEL.   getdns_context_destroy() returns after all of the needed
73       cleanup is done and callbacks are made.
74
75
76       If you are using getdns in a multi-threaded manner,  you  are  then  of
77       course using the underlying OpenSSL library multi-threaded and the ver‐
78       sion of that library in use might have a requirements  on  this  issue.
79       You  may  need  to provide one or two functions to allow it to function
80       properly. For example before you call getdns_context_create()  you  may
81       need   to   use   the   openssl  functions  CRYPTO_set_id_callback  and
82       CRYPTO_set_locking_callback to set up asynchronous operation (the   ap‐
83       plication  calls  these  functions  once  for initialisation).  Openssl
84       1.0.0 or later uses the CRYPTO_THREADID_set_callback function.
85
86
87       context Used to return the pointer to an opaque structure.  The  caller
88          passes  the  address  of  a  pointer (decl: getdns_context *context;
89          passed as &context) which will be populated as a result of returning
90          from  the function.  The result is a newly allocated and initialized
91          context (if there are no  errors).   In  the  getdns_destroy_context
92          function  this  is  the  context whose associated memory will be re‐
93          leased.
94
95
96       set_from_os If set_from_os is 0 then the caller must provide forwarding
97          name  servers if running in stub mode.  If set_from_os is 1 then the
98          system files are used to initialize the  context.   /etc/resolv.conf
99          is used to populate forwarders when running as a stub resolver (only
100          "nameserver" lines are recognized).  If set_from_os is 1  /etc/hosts
101          entries  are  preferred  before resorting to a DNS query.  Errors in
102          the system files will not prevent the context form  being  construc‐
103          ted.
104
105
106       userarg  In  the extended use case this argument is passed unchanged to
107          each of the memory management functions each time they are called.
108
109
110       malloc The function that will be used for creating response dicts  (and
111          the  members within the response dicts).  By default the system mal‐
112          loc is used.
113
114
115       realloc The function that will be used for creating response dicts (and
116          the members within the response dicts).  By default the system real‐
117          loc is used.
118
119
120       free The function that will be used for releasing storage for  response
121          dicts  (and  the members within the response dicts).  By default the
122          system free is used.
123
124
125

DESCRIPTION (LONG)

127       Many calls in the DNS API require a DNS context. A DNS context contains
128       the  information that the API needs in order to process DNS calls, such
129       as the locations of upstream DNS servers, DNSSEC trust anchors, and  so
130       on.  The  internal structure of the DNS context is opaque, and might be
131       different on each OS. When a context is passed to any function, it must
132       be an allocated context; the context must not be NULL.
133
134
135       A  typical  application  using  this  API doesn't need to know anything
136       about contexts. Basically, the application creates a  default  context,
137       uses  it  in the functions that require a context, and then deallocates
138       it when done. Context manipulation is available for more DNS-aware pro‐
139       grams, but is unlikely to be of interest to applications that just want
140       the results of lookups for A, AAAA, SRV, and PTR records.
141
142
143       It is expected that contexts in implementations of  the  API  will  not
144       necessarily be thread-safe, but they will not be thread-hostile. A con‐
145       text should not be used by multiple threads: create a new  context  for
146       use  on  a different thread. It is just fine for an application to have
147       many contexts, and some DNS-heavy applications will certainly  want  to
148       have many even if the application uses a single thread.
149
150
151       When  the context is used in the API for the first time and set_from_os
152       is 1, the API starts replacing some of the values with values from  the
153       OS,  such  as  those  that  would  be  found  in res_query(3), /etc/re‐
154       solv.conf, and so on, then proceeds with the  new  function.  Some  ad‐
155       vanced users will not want the API to change the values to the OS's de‐
156       faults; if set_from_os is 0, the API will not do  any  updates  to  the
157       initial  values  based on changes in the OS. For example, this might be
158       useful if the API is acting as a stub resolver that is using a specific
159       upstream recursive resolver chosen by the application, not the one that
160       might come back from DHCP.
161
162
163
164

RETURN VALUES

166       Upon successful completion each of these  functions  return  GETDNS_RE‐
167       TURN_GOOD , otherwise the following error values are returned:
168
169
170       GETDNS_RETURN_GENERIC_ERROR  memory allocation failed or some other un‐
171       toward thing happened while initializing the context
172
173
174       GETDNS_RETURN_BAD_CONTEXT   if   the   context   pointer   is   invalid
175       (getdns_context_destroy)
176
177
178       The  getdns_dict returned by getdns_context_get_api_information must be
179       destroyed by the called and includes the following name/value pairs:
180
181
182       version_string
183              a bindata containing a printable string of the  version  of  the
184              DNS API implemented by this library
185
186
187       implementation_string
188              a  bindata  containing a printable string set by the implementa‐
189              tion
190
191
192       resolution_type
193              an int equal to  GETDNS_RESOLUTION_RECURSING  or  GETDNS_RESOLU‐
194              TION_STUB
195
196
197       all_context
198              a  getdns_dict  with names for all the types of context, feed it
199              to getdns_pretty_print_dict (3) for something easily readable
200
201

EXAMPLES

203       TBD
204
205

FILES

207       /etc/hosts
208       /etc/resolv.conf
209
210

SEE ALSO

212       libgetdns(3),  getdns_address(3),  getdns_address_sync(3),  getdns_con‐
213       text_set(3), getdns_context_set_context_update_callback(3), getdns_gen‐
214       eral(3),   getdns_general_sync(3),   getdns_hostname(3),   getdns_host‐
215       name_sync(3), getdns_service(3), getdns_service_sync(3).
216
217
218
219
220getdns 1.7.3                     December 2015               getdns_context(3)
Impressum