]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
5b12fe6d | 2 | .\" and (C) Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" References consulted: | |
27 | .\" Linux libc source code | |
28 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
29 | .\" 386BSD man pages | |
30 | .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu) | |
31 | .\" Modified 2004-10-31 by aeb | |
32 | .\" | |
b8efb414 | 33 | .TH RESOLVER 3 2016-10-08 "GNU" "Linux Programmer's Manual" |
fea681da | 34 | .SH NAME |
5b12fe6d | 35 | res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend, |
c13182ef | 36 | res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, |
fea681da MK |
37 | dn_comp, dn_expand \- resolver routines |
38 | .SH SYNOPSIS | |
39 | .nf | |
40 | .B #include <netinet/in.h> | |
41 | .B #include <arpa/nameser.h> | |
42 | .B #include <resolv.h> | |
11e8504e | 43 | |
5b12fe6d MK |
44 | .B struct __res_state; |
45 | .B typedef struct __res_state *res_state; | |
11e8504e | 46 | |
519303a6 | 47 | .BI "int res_ninit(res_state " statep ); |
5b12fe6d | 48 | |
ef0e133f | 49 | .BI "int res_nquery(res_state " statep , |
5b12fe6d | 50 | .BI " const char *" dname ", int " class ", int " type , |
11e8504e MK |
51 | .BI " unsigned char *" answer ", int " anslen ); |
52 | ||
5b12fe6d MK |
53 | .BI "int res_nsearch(res_state " statep , |
54 | .BI " const char *" dname ", int " class ", int " type , | |
11e8504e MK |
55 | .BI " unsigned char *" answer ", int " anslen ); |
56 | ||
5b12fe6d MK |
57 | .BI "int res_nquerydomain(res_state " statep , |
58 | .BI " const char *" name ", const char *" domain , | |
11e8504e MK |
59 | .BI " int " class ", int " type ", unsigned char *" answer , |
60 | .BI " int " anslen ); | |
61 | ||
5b12fe6d MK |
62 | .BI "int res_nmkquery(res_state " statep , |
63 | .BI " int " op ", const char *" dname ", int " class , | |
11e8504e | 64 | .BI " int " type ", const unsigned char *" data ", int " datalen , |
5b12fe6d MK |
65 | .BI " const unsigned char *" newrr , |
66 | .BI " unsigned char *" buf ", int " buflen ); | |
11e8504e | 67 | |
5b12fe6d MK |
68 | .BI "int res_nsend(res_state " statep , |
69 | .BI " const unsigned char *" msg ", int " msglen , | |
11e8504e MK |
70 | .BI " unsigned char *" answer ", int " anslen ); |
71 | ||
0c5e1f65 | 72 | .BI "int dn_comp(const char *" exp_dn ", unsigned char *" comp_dn , |
11e8504e MK |
73 | .BI " int " length ", unsigned char **" dnptrs , |
74 | .BI " unsigned char **" lastdnptr ); | |
75 | ||
5b12fe6d MK |
76 | .BI "int dn_expand(const unsigned char *" msg , |
77 | .BI " const unsigned char *" eomorig , | |
11e8504e MK |
78 | .BI " const unsigned char *" comp_dn ", char *" exp_dn , |
79 | .BI " int " length ); | |
fea681da | 80 | .fi |
787dd4ad | 81 | .\" |
5b12fe6d | 82 | .SS Deprecated |
5b12fe6d MK |
83 | .nf |
84 | .B extern struct __res_state _res; | |
85 | ||
86 | .B int res_init(void); | |
87 | ||
88 | .BI "int res_query(const char *" dname ", int " class ", int " type , | |
89 | .BI " unsigned char *" answer ", int " anslen ); | |
90 | ||
91 | .BI "int res_search(const char *" dname ", int " class ", int " type , | |
92 | .BI " unsigned char *" answer ", int " anslen ); | |
93 | ||
94 | .BI "int res_querydomain(const char *" name ", const char *" domain , | |
95 | .BI " int " class ", int " type ", unsigned char *" answer , | |
96 | .BI " int " anslen ); | |
97 | ||
98 | .BI "int res_mkquery(int " op ", const char *" dname ", int " class , | |
99 | .BI " int " type ", const unsigned char *" data ", int " datalen , | |
100 | .BI " const unsigned char *" newrr , | |
101 | .BI " unsigned char *" buf ", int " buflen ); | |
102 | ||
103 | .BI "int res_send(const unsigned char *" msg ", int " msglen , | |
104 | .BI " unsigned char *" answer ", int " anslen ); | |
105 | .fi | |
fea681da | 106 | .sp |
e9329f6d | 107 | Link with \fI\-lresolv\fP. |
fea681da | 108 | .SH DESCRIPTION |
5b12fe6d MK |
109 | .B Note: |
110 | This page is incomplete (various resolver functions provided by glibc | |
111 | are not described) and likely out of date. | |
112 | ||
113 | The functions described below make queries to and interpret | |
114 | the responses from Internet domain name servers. | |
115 | ||
116 | The API consists of a set of more modern, reentrant functions | |
117 | and an older set of nonreentrant functions that have been superseded. | |
118 | The traditional resolver interfaces such as | |
119 | .BR res_init () | |
120 | and | |
121 | .BR res_query () | |
122 | use some static (global) state stored in the | |
123 | .I _res | |
124 | structure, rendering these functions non-thread-safe. | |
125 | BIND 8.2 introduced a set of new interfaces | |
126 | .BR res_ninit (), | |
127 | .BR res_nquery (), | |
128 | and so on, which take a | |
129 | .I res_state | |
130 | as their first argument, so you can use a per-thread resolver state. | |
131 | ||
60a90ecd | 132 | The |
5b12fe6d MK |
133 | .BR res_ninit () |
134 | and | |
60a90ecd | 135 | .BR res_init () |
5b12fe6d | 136 | functions read the configuration files (see |
f0414487 | 137 | .BR resolv.conf (5)) |
0921ce4a | 138 | to get the default domain name and name |
c13182ef MK |
139 | server address(es). |
140 | If no server is given, the local host is tried. | |
fea681da | 141 | If no domain is given, that associated with the local host is used. |
653ba10a MK |
142 | It can be overridden with the environment variable |
143 | .BR LOCALDOMAIN . | |
5b12fe6d MK |
144 | .BR res_ninit () |
145 | or | |
60a90ecd MK |
146 | .BR res_init () |
147 | is normally executed by the first call to one of the | |
fea681da | 148 | other functions. |
5b12fe6d | 149 | |
60a90ecd | 150 | The |
5b12fe6d MK |
151 | .BR res_nquery () |
152 | and | |
60a90ecd | 153 | .BR res_query () |
5b12fe6d | 154 | functions query the name server for the |
3f624b93 | 155 | fully qualified domain name \fIname\fP of specified \fItype\fP and |
c13182ef MK |
156 | \fIclass\fP. |
157 | The reply is left in the buffer \fIanswer\fP of length | |
fea681da | 158 | \fIanslen\fP supplied by the caller. |
5b12fe6d | 159 | |
60a90ecd | 160 | The |
5b12fe6d MK |
161 | .BR res_nsearch () |
162 | and | |
60a90ecd | 163 | .BR res_search () |
5b12fe6d MK |
164 | functions make a query and waits for the response like |
165 | .BR res_nquery () | |
166 | and | |
60a90ecd | 167 | .BR res_query (), |
5b12fe6d | 168 | but in addition they implement the default and search |
653ba10a MK |
169 | rules controlled by |
170 | .B RES_DEFNAMES | |
171 | and | |
172 | .B RES_DNSRCH | |
173 | (see description of | |
fea681da | 174 | \fI_res\fP options below). |
5b12fe6d | 175 | |
60a90ecd | 176 | The |
5b12fe6d MK |
177 | .BR res_nquerydomain () |
178 | and | |
60a90ecd | 179 | .BR res_querydomain () |
5b12fe6d MK |
180 | functions make a query using |
181 | .BR res_nquery ()/ res_query () | |
fea681da | 182 | on the concatenation of \fIname\fP and \fIdomain\fP. |
5b12fe6d | 183 | |
60a90ecd | 184 | The following functions are lower-level routines used by |
5b12fe6d MK |
185 | .BR res_query ()/ res_query (). |
186 | ||
60a90ecd | 187 | The |
5b12fe6d MK |
188 | .BR res_nmkquery () |
189 | and | |
60a90ecd | 190 | .BR res_mkquery () |
5b12fe6d | 191 | functions construct a query message in \fIbuf\fP |
c13182ef MK |
192 | of length \fIbuflen\fP for the domain name \fIdname\fP. |
193 | The query type | |
653ba10a MK |
194 | \fIop\fP is usually |
195 | .BR QUERY , | |
196 | but can be any of the types defined in | |
be7fff26 MK |
197 | \fI<arpa/nameser.h>\fP. |
198 | \fInewrr\fP is currently unused. | |
5b12fe6d | 199 | |
60a90ecd | 200 | The |
5b12fe6d MK |
201 | .BR res_nsend () |
202 | and | |
60a90ecd | 203 | .BR res_send () |
5b12fe6d | 204 | function send a preformatted query given in |
fea681da | 205 | \fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP |
c13182ef | 206 | which is of length \fIanslen\fP. |
5b12fe6d MK |
207 | They will call |
208 | .BR res_ninit ()/ res_init () | |
209 | if it has not already been called. | |
fea681da | 210 | .PP |
60a90ecd MK |
211 | The |
212 | .BR dn_comp () | |
213 | function compresses the domain name \fIexp_dn\fP | |
fea681da MK |
214 | and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP. |
215 | The compression uses an array of pointers \fIdnptrs\fP to previously | |
c13182ef MK |
216 | compressed names in the current message. |
217 | The first pointer points | |
218 | to the beginning of the message and the list ends with NULL. | |
219 | The limit of the array is specified by \fIlastdnptr\fP. | |
220 | If \fIdnptr\fP is NULL, domain names are not compressed. | |
221 | If \fIlastdnptr\fP is NULL, the list | |
fea681da MK |
222 | of labels is not updated. |
223 | .PP | |
653ba10a MK |
224 | The |
225 | .BR dn_expand () | |
226 | function expands the compressed domain name | |
fea681da | 227 | \fIcomp_dn\fP to a full domain name, which is placed in the buffer |
c13182ef MK |
228 | \fIexp_dn\fP of size \fIlength\fP. |
229 | The compressed name is contained | |
fea681da MK |
230 | in a query or reply message, and \fImsg\fP points to the beginning of |
231 | the message. | |
232 | .PP | |
5b12fe6d MK |
233 | The resolver routines use configuration and state information |
234 | contained in a | |
235 | .IR __res_state | |
236 | structure (either passed as the | |
237 | .IR statep | |
238 | argument, or in the global variable | |
239 | .IR _res , | |
240 | in the case of the older nonreentrant functions). | |
241 | The only field of this structure that is normally manipulated by the | |
242 | user is the | |
243 | .IR options | |
244 | field. | |
653ba10a | 245 | This field can contain the bitwise "OR" |
fea681da | 246 | of the following options: |
fea681da MK |
247 | .TP |
248 | .B RES_INIT | |
60a90ecd | 249 | True if |
5b12fe6d MK |
250 | .BR res_ninit () |
251 | or | |
60a90ecd MK |
252 | .BR res_init () |
253 | has been called. | |
fea681da MK |
254 | .TP |
255 | .B RES_DEBUG | |
256 | Print debugging messages. | |
33a0ccb2 | 257 | This option is available only if glibc was built with debugging enabled, |
7d63c0a4 MK |
258 | .\" See resolv/README. |
259 | .\" Support for RES_DEBUG was made conditional in glibc 2.2. | |
260 | which is not the default. | |
fea681da MK |
261 | .TP |
262 | .B RES_AAONLY | |
988db661 | 263 | Accept authoritative answers only. |
60a90ecd MK |
264 | .BR res_send () |
265 | continues until | |
ffb9f8b3 SA |
266 | it finds an authoritative answer or returns an error. |
267 | [Not currently implemented]. | |
fea681da MK |
268 | .TP |
269 | .B RES_USEVC | |
270 | Use TCP connections for queries rather than UDP datagrams. | |
271 | .TP | |
272 | .B RES_PRIMARY | |
273 | Query primary domain name server only. | |
ffb9f8b3 | 274 | [Not currently implemented]. |
fea681da MK |
275 | .TP |
276 | .B RES_IGNTC | |
c13182ef | 277 | Ignore truncation errors. |
ffb9f8b3 | 278 | Don't retry with TCP. |
fea681da MK |
279 | .TP |
280 | .B RES_RECURSE | |
c13182ef MK |
281 | Set the recursion desired bit in queries. |
282 | Recursion is carried out | |
60a90ecd MK |
283 | by the domain name server, not by |
284 | .BR res_send (). | |
c13182ef | 285 | [Enabled by default]. |
fea681da MK |
286 | .TP |
287 | .B RES_DEFNAMES | |
60a90ecd MK |
288 | If set, |
289 | .BR res_search () | |
290 | will append the default domain name to | |
88879aeb | 291 | single component names\(emthat is, those that do not contain a dot. |
fea681da MK |
292 | [Enabled by default]. |
293 | .TP | |
294 | .B RES_STAYOPEN | |
653ba10a MK |
295 | Used with |
296 | .B RES_USEVC | |
297 | to keep the TCP connection open between queries. | |
fea681da MK |
298 | .TP |
299 | .B RES_DNSRCH | |
60a90ecd MK |
300 | If set, |
301 | .BR res_search () | |
ddaec46d | 302 | will search for hostnames in the current |
c13182ef MK |
303 | domain and in parent domains. |
304 | This option is used by | |
fea681da MK |
305 | .BR gethostbyname (3). |
306 | [Enabled by default]. | |
ffb9f8b3 SA |
307 | .TP |
308 | .B RES_INSECURE1 | |
25fe58e4 SA |
309 | Accept a response from a wrong server. |
310 | This can be used to detect potential security hazards, | |
311 | but you need to compile glibc with debugging enabled and use | |
312 | .B RES_DEBUG | |
313 | option (for debug purpose only). | |
ffb9f8b3 SA |
314 | .TP |
315 | .B RES_INSECURE2 | |
25fe58e4 SA |
316 | Accept a response which contains a wrong query. |
317 | This can be used to detect potential security hazards, | |
318 | but you need to compile glibc with debugging enabled and use | |
319 | .B RES_DEBUG | |
320 | option (for debug purpose only). | |
ffb9f8b3 SA |
321 | .TP |
322 | .B RES_NOALIASES | |
323 | Disable usage of | |
324 | .B HOSTALIASES | |
325 | environment variable. | |
326 | .TP | |
327 | .B RES_USE_INET6 | |
328 | Try an AAAA query before an A query inside the | |
119a3851 | 329 | .BR gethostbyname (3) |
ffb9f8b3 SA |
330 | function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records |
331 | are found but an A record set exists. | |
332 | .TP | |
333 | .B RES_ROTATE | |
334 | Causes round-robin selection of name servers from among those listed. | |
335 | This has the effect of spreading the query load among all listed servers, | |
336 | rather than having all clients try the first listed server first every | |
337 | time. | |
338 | .TP | |
339 | .B RES_NOCHECKNAME | |
340 | Disable the modern BIND checking of incoming hostnames and mail names | |
341 | for invalid characters such as underscore (_), non-ASCII, | |
342 | or control characters. | |
343 | [Not currently implemented]. | |
344 | .TP | |
345 | .B RES_KEEPTSIG | |
346 | Do not strip TSIG records. | |
347 | [Not currently implemented]. | |
348 | .TP | |
349 | .B RES_BLAST | |
350 | Send each query simultaneously and recursively to all servers. | |
351 | Note this option overrides | |
352 | .BR RES_ROTATE . | |
353 | .TP | |
354 | .BR RES_USEBSTRING " (since glibc 2.3.4)" | |
355 | Make reverse IPv6 lookups using the bit-label format described in RFC 2673; | |
356 | if this option is not set, then nibble format is used. | |
357 | .TP | |
358 | .B RES_NOIP6DOTINT | |
359 | Use | |
360 | .I ip6.arpa | |
361 | zone in IPv6 reverse lookup instead of | |
362 | .IR ip6.int , | |
363 | which is deprecated since glibc 2.3.4. | |
364 | [Enabled by default]. | |
365 | .TP | |
366 | .BR RES_USE_EDNS0 " (since glibc 2.6)" | |
367 | Enables support for the DNS extensions (EDNS0) described in RFC 2671. | |
368 | .TP | |
369 | .BR RES_SNGLKUP " (since glibc 2.10)" | |
370 | By default, glibc performs IPv4 and IPv6 lookups in parallel since | |
371 | version 2.9. | |
372 | Some appliance DNS servers cannot handle these queries properly | |
373 | and make the requests time out. | |
374 | This option disables the behavior and makes glibc | |
375 | perform the IPv6 and IPv4 requests sequentially | |
376 | (at the cost of some slowdown of the resolving process). | |
377 | .TP | |
378 | .B RES_SNGLKUPREOP | |
379 | When | |
380 | .B RES_SNGLKUP | |
381 | option is enabled, opens a new socket for the each request. | |
382 | .TP | |
383 | .B RES_USE_DNSSEC | |
384 | Use DNSSEC with OK bit in OPT record. | |
385 | This option implies | |
386 | .BR RES_USE_EDNS0 . | |
387 | .TP | |
388 | .B RES_NOTLDQUERY | |
389 | Do not look up unqualified name as a top-level domain (TLD). | |
390 | .TP | |
391 | .B RES_DEFAULT | |
392 | Default option which implies: | |
393 | .BR RES_RECURSE , | |
394 | .BR RES_DEFNAMES , | |
395 | .BR RES_DNSRCH | |
396 | and | |
397 | .BR RES_NOIP6DOTINT . | |
787dd4ad | 398 | .\" |
47297adb | 399 | .SH RETURN VALUE |
60a90ecd | 400 | The |
5b12fe6d MK |
401 | .BR res_ninit () |
402 | and | |
60a90ecd | 403 | .BR res_init () |
5b12fe6d | 404 | functions return 0 on success, or \-1 if an error |
fea681da MK |
405 | occurs. |
406 | .PP | |
60a90ecd | 407 | The |
5b12fe6d | 408 | .BR res_nquery (), |
60a90ecd | 409 | .BR res_query (), |
5b12fe6d | 410 | .BR res_nsearch (), |
60a90ecd | 411 | .BR res_search (), |
5b12fe6d | 412 | .BR res_nquerydomain (), |
60a90ecd | 413 | .BR res_querydomain (), |
5b12fe6d MK |
414 | .BR res_nmkquery (), |
415 | .BR res_mkquery (), | |
416 | .BR res_nsend (), | |
60a90ecd MK |
417 | and |
418 | .BR res_send () | |
419 | functions return the length | |
fea681da MK |
420 | of the response, or \-1 if an error occurs. |
421 | .PP | |
60a90ecd MK |
422 | The |
423 | .BR dn_comp () | |
424 | and | |
425 | .BR dn_expand () | |
426 | functions return the length | |
fea681da MK |
427 | of the compressed name, or \-1 if an error occurs. |
428 | .SH FILES | |
429 | .nf | |
430 | /etc/resolv.conf resolver configuration file | |
431 | /etc/host.conf resolver configuration file | |
432 | .fi | |
40221931 ZL |
433 | .SH ATTRIBUTES |
434 | For an explanation of the terms used in this section, see | |
435 | .BR attributes (7). | |
436 | .TS | |
437 | allbox; | |
8f797700 | 438 | lbw34 lb lb |
40221931 ZL |
439 | l l l. |
440 | Interface Attribute Value | |
441 | T{ | |
442 | .BR res_ninit (), | |
443 | .BR res_nquery (), | |
8f797700 | 444 | .br |
40221931 ZL |
445 | .BR res_nsearch (), |
446 | .BR res_nquerydomain (), | |
447 | .BR res_nsend () | |
448 | T} Thread safety MT-Safe locale | |
449 | T{ | |
450 | .BR res_nmkquery (), | |
451 | .BR dn_comp (), | |
8f797700 | 452 | .br |
40221931 ZL |
453 | .BR dn_expand () |
454 | T} Thread safety MT-Safe | |
455 | .TE | |
456 | ||
47297adb | 457 | .SH CONFORMING TO |
44a2c328 | 458 | 4.3BSD. |
47297adb | 459 | .SH SEE ALSO |
fea681da | 460 | .BR gethostbyname (3), |
bc7c3dc5 | 461 | .BR resolv.conf (5), |
aca92158 | 462 | .BR resolver (5), |
fea681da | 463 | .BR hostname (7), |
b95582c7 | 464 | .BR named (8) |
5b12fe6d MK |
465 | |
466 | The GNU C library source file | |
467 | .IR resolv/README . |