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

NAME

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
16

LIBRARY

18       DNS Resolver library (libgetdns, -lgetdns)
19
20

SYNOPSIS

22       #include <getdns.h>
23
24       getdns_return_t
25       getdns_context_set_append_name (getdns_context_t context,
26          getdns_append_name_t when_to_append)
27
28       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
32       getdns_return_t
33       getdns_context_set_dns_root_servers (getdns_context_t context,
34          getdns_list *root_addresses)
35
36       getdns_return_t
37       getdns_context_set_dns_transport (getdns_context_t context,
38          uint16_t transport)
39
40       getdns_return_t
41       getdns_contet_set_dnssec_allowed_skew (getdns_context *context,
42          uint32_t skew_seconds)
43
44       getdns_return_t
45       getdns_contet_set_dnssec_trust_anchors (getdns_context *context,
46          getdns_list *trust_anchors)
47
48       getdns_return_t
49       getdns_context_set_follow_redirects (getdns_context_t context,
50          getdns_redirects_t followredir)
51
52       getdns_return_t
53       getdns_context_set_limit_outstanding_queries (getdns_context_t context,
54          uint16_t limit)
55
56       getdns_return_t
57       getdns_context_set_namespaces (getdns_context_t context,
58          size_t namespace_count,
59          uint16_t *namespaces)
60
61       getdns_return_t
62       getdns_context_set_resolution_type (getdns_context_t context,
63          uint16_t restype)
64
65       getdns_return_t
66       getdns_context_set_suffix (getdns_context *context,
67          getdns_list *suffixes)
68
69       getdns_return_t
70       getdns_context_set_timeout (getdns_context_t context,
71          uint16_t timeout)
72
73

DESCRIPTION

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
80
81       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
85
86       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
90
91       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
94
95       getdns_context_set_dnssec_trust_anchors allows the  caller  to  specify
96       trust anchors as alternatives to the default trust anchors
97
98
99       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
103
104       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
109
110       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
115
116       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
120
121       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
125
126       getdns_context_set_resolution_type  specifies  whether  DNS queries are
127       performed with non-recursive lookups or as a stub resolver.
128
129
130       getdns_context_set_suffix Append suffixes to domain names prior to exe‐
131       cuting the lookup based on getdns_context_set_append_name.
132
133
134       getdns_context_set_timeout specifies the number of milliseconds the API
135       will wait for a response.
136
137
138       context a previously allocated and initialized getdns_context
139
140
141       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
147
148       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
154
155       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
160
161       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
166
167       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
172
173       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
187
188       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
192
193       seconds_skew  the  number  of  seconds skew allowed in either direction
194          when checking an RRSIGs expiration and inception fields.
195
196
197       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
202
203       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
207
208       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
212
213       when_to_append The value is
214
215          ·  GETDNS_APPEND_NAME_ALWAYS,
216
217          ·  GETDNS_APPEND_NAME_ONLY_TO_SINGLE_LABEL_AFTER_FAILURE,
218
219          ·  GETDNS_APPEND_NAME_ONLY_TO_MULTIPLE_LABEL_NAME_AFTER_FAILURE, or
220
221          ·  GETDNS_APPEND_NAME_NEVER.
222
223
224
225

RETURN VALUES

227       Upon  successful  completion  the functions return GETDNS_RETURN_GOOD ,
228       otherwise the following error values are returned:
229
230
231       GETDNS_RETURN_BAD_CONTEXT if the context pointer is invalid
232
233       GETDNS_RETURN_CONTEXT_UPDATE_FAIL if there was a problem  updating  the
234       context
235
236

EXAMPLES

238       TBD
239
240

FILES

242       /etc/hosts
243       /etc/resolv.conf
244
245

SEE ALSO

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).
250
251
252
253
254getdns 1.6.0                     December 2015           getdns_context_set(3)
Impressum