1getdns_context(3) getdns getdns_context(3)
3
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
14 DNS Resolver library (libgetdns, -lgetdns)
15
18 #include <getdns.h>
19 getdns_return_t
21 getdns_context_create (getdns_context ** context,
22 int set_from_os)
23 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 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 void
41 getdns_context_destroy (getdns_context *context)
42 getdns_dict *
44 getdns_context_get_api_information (getdns_context *context)
45
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 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 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 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 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 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 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 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 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 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 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 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
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 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 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 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
166 Upon successful completion each of these functions return GETDNS_RE‐
167 TURN_GOOD , otherwise the following error values are returned:
168 GETDNS_RETURN_GENERIC_ERROR memory allocation failed or some other un‐
171 toward thing happened while initializing the context
172 GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid
175 (getdns_context_destroy)
176 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 version_string
183 a bindata containing a printable string of the version of the
184 DNS API implemented by this library
185 implementation_string
188 a bindata containing a printable string set by the implementa‐
189 tion
190 resolution_type
193 an int equal to GETDNS_RESOLUTION_RECURSING or GETDNS_RESOLU‐
194 TION_STUB
195 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
203 TBD
204
207 /etc/hosts
208 /etc/resolv.conf
209
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).
216getdns 1.7.3 December 2015 getdns_context(3)