1getdns_context_set(3) getdns getdns_context_set(3)
3
7 getdns_context_set_append_name, getdns_context_set_context_update_call‐
8 back, getdns_context_set_dns_root_servers, getdns_con‐
9 text_set_dns_transport, getdns_context_set_dnssec_trust_anchors,
10 getdns_context_set_dnssec_allowed_skew, getdns_context_set_follow_redi‐
11 rects, getdns_context_set_limit_outstanding_queries, getdns_con‐
12 text_set_namespaces, getdns_context_set_resolution_type, getdns_con‐
13 text_set_suffix, getdns_context_set_timeout, -- getdns context manipu‐
14 lation routines
15
18 DNS Resolver library (libgetdns, -lgetdns)
19
22 #include <getdns.h>
23 getdns_return_t
25 getdns_context_set_append_name (getdns_context_t context,
26 getdns_append_name_t when_to_append)
27 getdns_return_t
29 getdns_context_set_context_update_callback (getdns_context_t context,
30 (*callback)(struct getdns_context *context, uint16_t changed_item))
31 getdns_return_t
33 getdns_context_set_dns_root_servers (getdns_context_t context,
34 getdns_list *root_addresses)
35 getdns_return_t
37 getdns_context_set_dns_transport (getdns_context_t context,
38 uint16_t transport)
39 getdns_return_t
41 getdns_contet_set_dnssec_allowed_skew (getdns_context *context,
42 uint32_t skew_seconds)
43 getdns_return_t
45 getdns_contet_set_dnssec_trust_anchors (getdns_context *context,
46 getdns_list *trust_anchors)
47 getdns_return_t
49 getdns_context_set_follow_redirects (getdns_context_t context,
50 getdns_redirects_t followredir)
51 getdns_return_t
53 getdns_context_set_limit_outstanding_queries (getdns_context_t context,
54 uint16_t limit)
55 getdns_return_t
57 getdns_context_set_namespaces (getdns_context_t context,
58 size_t namespace_count,
59 uint16_t *namespaces)
60 getdns_return_t
62 getdns_context_set_resolution_type (getdns_context_t context,
63 uint16_t restype)
64 getdns_return_t
66 getdns_context_set_suffix (getdns_context *context,
67 getdns_list *suffixes)
68 getdns_return_t
70 getdns_context_set_timeout (getdns_context_t context,
71 uint16_t timeout)
72
75 These functions are used to manipulate a previously allocated and ini‐
76 tialized context, see getdns_context (3) for more details on the func‐
77 tions used to allocate, initialized and destroy contexts and for a more
78 detailed discussion of the getdns_context in general.
79 getdns_context_set_append_name Specifies whether to append a suffix
82 supplied via getdns_context_set_suffix (3) to the query string before
83 the API starts resolving a name.
84 getdns_context_set_context_update_callback sets a function that will be
87 called if changes to the system files (for example /etc/resolv.conf and
88 /etc/hosts).
89 getdns_context_set_dns_transport specifies the transport used for DNS
92 lookups, the default is to use UDP and fall back to TCP as needed.
93 getdns_context_set_dnssec_trust_anchors allows the caller to specify
96 trust anchors as alternatives to the default trust anchors
97 getdns_context_set_dnssec_allowed_skew set the number of seconds skew
100 allowed in either direction when checking an RRSIGs expiration and
101 inception fields, the default is 0.
102 getdns_context_set_limit_outstanding_queries specifies the maximum num‐
105 ber of outstanding DNS queries, the API will queue queries over this
106 limit until current queries are answers and will then automatically
107 issue the queries on the queue.
108 getdns_context_set_dns_root_servers provides an alternate set of
111 addresses to use to look up the top level domains. The default (if
112 this function is not called) is the list of IANA root servers (think of
113 this as the root hints).
114 getdns_context_set_follow_redirects specifies whether or not DNS
117 queries follow redirects (CNAME and DNAME), the default behavior is to
118 follow redirects and return the eventual target.
119 getdns_context_set_namespaces sets the namespaces to be used by the
122 resolver, the default is DNS and then local files. Future implementa‐
123 tions will support netbios, mdns, and nis.
124 getdns_context_set_resolution_type specifies whether DNS queries are
127 performed with non-recursive lookups or as a stub resolver.
128 getdns_context_set_suffix Append suffixes to domain names prior to exe‐
131 cuting the lookup based on getdns_context_set_append_name.
132 getdns_context_set_timeout specifies the number of milliseconds the API
135 will wait for a response.
136 context a previously allocated and initialized getdns_context
139 callback a callback function that will be called when changes are made
142 to the system files (/etc/resolv.conf and /etc/hosts) for contexts
143 created with set_from_os = 1. When this function is called the
144 changed_item parameter indicates which item in the context has
145 changed.
146 root_addresses This is a list of getdns_dict types that each identify a
149 single root server to use to look up top level domains. Each dic‐
150 tionary includes two names, address_type , a bindata containing the
151 string "IPv4" or "IPv6" and address_data a bindata containing the IP
152 address.
153 transport may be one of GETDNS_CONTEXT_UDP_FIRST_AND_FALL_BACK_TO_TCP,
156 GETDNS_CONTEXT_UDP_ONLY, GETDNS_CONTEXT_TCP_ONLY, GETDNS_CON‐
157 TEXT_TCP_ONLY_KEEP_CONNECTIONS_OPEN. If you need more information
158 on what each of these means reread the mnemonic and take a guess ;)
159 followredir If set to GETDNS_REDIRECTS_FOLLOW (the default) then the
162 eventual target of the redirect is returned. If set to GETDNS_REDI‐
163 RECTS_DO_NOT_FOLLOW then the CNAME or DNAME is returned and NOT the
164 eventual target.
165 limit the maximum number of concurrent outstanding (unanswered) DNS
168 queries, if exceeded the API will queue queries and issue them as
169 the number of outstanding queries drops. A value of 0 indicates
170 that there is no limit.
171 namespaces The namespaces array contains an ordered list of namespaces
174 that will be queried. Important: this context setting is ignored for
175 the getdns_general and getdns_general_sync functions; it is used for
176 the other functions. The values are GETDNS_CONTEXT_NAMESPACE_DNS,
177 GETDNS_CONTEXT_NAMESPACE_LOCALNAMES, GETDNS_CONTEXT_NAMESPACE_NET‐
178 BIOS, GETDNS_CONTEXT_NAMESPACE_MDNS, and GETDNS_CONTEXT_NAMES‐
179 PACE_NIS. When a normal lookup is done, the API does the lookups in
180 the order given and stops when it gets the first result; a different
181 method with the same result would be to run the queries in parallel
182 and return when it gets the first result. Because lookups might be
183 done over different mechanisms because of the different namespaces,
184 there can be information leakage that is similar to that seen with
185 getaddrinfo(). The default is determined by the OS.
186 restype can be set to either GETDNS_CONTEXT_RECURSIVE (the default) or
189 GETDNS_CONTEXT_STUB (requires that forwarders be specified by the
190 caller).
191 seconds_skew the number of seconds skew allowed in either direction
194 when checking an RRSIGs expiration and inception fields.
195 suffixes A list of bindatas that are strings that are to be appended
198 based on getdns_context_set_append_name. The values here follow the
199 rules in section 2.1 of RFC 4343 to allow non-ASCII octets and spe‐
200 cial characters in labels.
201 timeout the number of milliseconds the API will wait for a response,
204 after which the callback will be invoked (or the synchronous func‐
205 tion will return) with a timeout error.
206 trust_anchors list of bindatas that are the DNSSEC trust anchors
209 expressed as RDATA from the DNSKEY resource records, the default are
210 supplied by the IANA root.
211 when_to_append The value is
214 · GETDNS_APPEND_NAME_ALWAYS,
216 · GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,
218 · GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, or
220 · GETDNS_APPEND_NAME_NEVER.
222
227 Upon successful completion the functions return GETDNS_RETURN_GOOD ,
228 otherwise the following error values are returned:
229 GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid
232 GETDNS_RETURN_CONTEXT_UPDATE_FAIL if there was a problem updating the
234 context
235
238 TBD
239
242 /etc/hosts
243 /etc/resolv.conf
244
247 libgetdns(3), getdns_address(3), getdns_address_sync(3), getdns_con‐
248 text(3), getdns_general(3), getdns_general_sync(3), getdns_hostname(3),
249 getdns_hostname_sync(3), getdns_service(3), getdns_service_sync(3).
250getdns 1.6.0 December 2015 getdns_context_set(3)