| blob | 32c0011cefd43766dc02f233584d68f5820daf50 |
1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
2 .\" and (C) Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\"
4 .\" %%%LICENSE_START(VERBATIM)
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.
13 .\"
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.
21 .\"
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" %%%LICENSE_END
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 .\"
33 .TH RESOLVER 3 2020-12-21 "GNU" "Linux Programmer's Manual"
34 .SH NAME
35 res_ninit, res_nclose, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend,
36 res_init, res_query, res_search, res_querydomain, res_mkquery, res_send,
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>
43 .PP
44 .B struct __res_state;
45 .B typedef struct __res_state *res_state;
46 .PP
47 .BI "int res_ninit(res_state " statep );
48 .PP
49 .BI "void res_nclose(res_state " statep );
50 .PP
51 .BI "int res_nquery(res_state " statep ,
52 .BI " const char *" dname ", int " class ", int " type ,
53 .BI " unsigned char *" answer ", int " anslen );
54 .PP
55 .BI "int res_nsearch(res_state " statep ,
56 .BI " const char *" dname ", int " class ", int " type ,
57 .BI " unsigned char *" answer ", int " anslen );
58 .PP
59 .BI "int res_nquerydomain(res_state " statep ,
60 .BI " const char *" name ", const char *" domain ,
61 .BI " int " class ", int " type ", unsigned char *" answer ,
62 .BI " int " anslen );
63 .PP
64 .BI "int res_nmkquery(res_state " statep ,
65 .BI " int " op ", const char *" dname ", int " class ,
66 .BI " int " type ", const unsigned char *" data ", int " datalen ,
67 .BI " const unsigned char *" newrr ,
68 .BI " unsigned char *" buf ", int " buflen );
69 .PP
70 .BI "int res_nsend(res_state " statep ,
71 .BI " const unsigned char *" msg ", int " msglen ,
72 .BI " unsigned char *" answer ", int " anslen );
73 .PP
74 .BI "int dn_comp(const char *" exp_dn ", unsigned char *" comp_dn ,
75 .BI " int " length ", unsigned char **" dnptrs ,
76 .BI " unsigned char **" lastdnptr );
77 .PP
78 .BI "int dn_expand(const unsigned char *" msg ,
79 .BI " const unsigned char *" eomorig ,
80 .BI " const unsigned char *" comp_dn ", char *" exp_dn ,
81 .BI " int " length );
82 .fi
83 .\"
84 .SS Deprecated
85 .nf
86 .B extern struct __res_state _res;
87 .PP
88 .B int res_init(void);
89 .PP
90 .BI "int res_query(const char *" dname ", int " class ", int " type ,
91 .BI " unsigned char *" answer ", int " anslen );
92 .PP
93 .BI "int res_search(const char *" dname ", int " class ", int " type ,
94 .BI " unsigned char *" answer ", int " anslen );
95 .PP
96 .BI "int res_querydomain(const char *" name ", const char *" domain ,
97 .BI " int " class ", int " type ", unsigned char *" answer ,
98 .BI " int " anslen );
99 .PP
100 .BI "int res_mkquery(int " op ", const char *" dname ", int " class ,
101 .BI " int " type ", const unsigned char *" data ", int " datalen ,
102 .BI " const unsigned char *" newrr ,
103 .BI " unsigned char *" buf ", int " buflen );
104 .PP
105 .BI "int res_send(const unsigned char *" msg ", int " msglen ,
106 .BI " unsigned char *" answer ", int " anslen );
107 .fi
108 .PP
109 Link with \fI\-lresolv\fP.
110 .SH DESCRIPTION
111 .B Note:
112 This page is incomplete (various resolver functions provided by glibc
113 are not described) and likely out of date.
114 .PP
115 The functions described below make queries to and interpret
116 the responses from Internet domain name servers.
117 .PP
118 The API consists of a set of more modern, reentrant functions
119 and an older set of nonreentrant functions that have been superseded.
120 The traditional resolver interfaces such as
121 .BR res_init ()
122 and
123 .BR res_query ()
124 use some static (global) state stored in the
125 .I _res
126 structure, rendering these functions non-thread-safe.
127 BIND 8.2 introduced a set of new interfaces
128 .BR res_ninit (),
129 .BR res_nquery (),
130 and so on, which take a
131 .I res_state
132 as their first argument, so you can use a per-thread resolver state.
133 .PP
134 The
135 .BR res_ninit ()
136 and
137 .BR res_init ()
138 functions read the configuration files (see
139 .BR resolv.conf (5))
140 to get the default domain name and name
141 server address(es).
142 If no server is given, the local host is tried.
143 If no domain is given, that associated with the local host is used.
144 It can be overridden with the environment variable
145 .BR LOCALDOMAIN .
146 .BR res_ninit ()
147 or
148 .BR res_init ()
149 is normally executed by the first call to one of the
150 other functions.
151 Every call to
152 .BR res_ninit ()
153 requires a corresponding call to
154 .BR res_nclose ()
155 to free memory allocated by
156 .BR res_ninit ()
157 and subsequent calls to
158 .BR res_nquery ().
159 .PP
160 The
161 .BR res_nquery ()
162 and
163 .BR res_query ()
164 functions query the name server for the
165 fully qualified domain name \fIname\fP of specified \fItype\fP and
166 \fIclass\fP.
167 The reply is left in the buffer \fIanswer\fP of length
168 \fIanslen\fP supplied by the caller.
169 .PP
170 The
171 .BR res_nsearch ()
172 and
173 .BR res_search ()
174 functions make a query and waits for the response like
175 .BR res_nquery ()
176 and
177 .BR res_query (),
178 but in addition they implement the default and search
179 rules controlled by
180 .B RES_DEFNAMES
181 and
182 .B RES_DNSRCH
183 (see description of
184 \fI_res\fP options below).
185 .PP
186 The
187 .BR res_nquerydomain ()
188 and
189 .BR res_querydomain ()
190 functions make a query using
191 .BR res_nquery ()/ res_query ()
192 on the concatenation of \fIname\fP and \fIdomain\fP.
193 .PP
194 The following functions are lower-level routines used by
195 .BR res_nquery ()/ res_query ().
196 .PP
197 The
198 .BR res_nmkquery ()
199 and
200 .BR res_mkquery ()
201 functions construct a query message in \fIbuf\fP
202 of length \fIbuflen\fP for the domain name \fIdname\fP.
203 The query type
204 \fIop\fP is one of the following (typically
205 .BR QUERY ):
206 .TP
207 .B QUERY
208 Standard query.
209 .TP
210 .B IQUERY
211 Inverse query.
212 This option was removed in glibc 2.26,
213 .\" commit e4e794841e3140875f2aa86b90e2ada3d61e1244
214 since it has not been supported by DNS servers for a very long time.
215 .TP
216 .B NS_NOTIFY_OP
217 Notify secondary of SOA (Start of Authority) change.
218 .PP
219 \fInewrr\fP is currently unused.
220 .PP
221 The
222 .BR res_nsend ()
223 and
224 .BR res_send ()
225 function send a preformatted query given in
226 \fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP
227 which is of length \fIanslen\fP.
228 They will call
229 .BR res_ninit ()/ res_init ()
230 if it has not already been called.
231 .PP
232 The
233 .BR dn_comp ()
234 function compresses the domain name \fIexp_dn\fP
235 and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP.
236 The compression uses an array of pointers \fIdnptrs\fP to previously
237 compressed names in the current message.
238 The first pointer points
239 to the beginning of the message and the list ends with NULL.
240 The limit of the array is specified by \fIlastdnptr\fP.
241 If \fIdnptr\fP is NULL, domain names are not compressed.
242 If \fIlastdnptr\fP is NULL, the list
243 of labels is not updated.
244 .PP
245 The
246 .BR dn_expand ()
247 function expands the compressed domain name
248 \fIcomp_dn\fP to a full domain name, which is placed in the buffer
249 \fIexp_dn\fP of size \fIlength\fP.
250 The compressed name is contained
251 in a query or reply message, and \fImsg\fP points to the beginning of
252 the message.
253 .PP
254 The resolver routines use configuration and state information
255 contained in a
256 .IR __res_state
257 structure (either passed as the
258 .IR statep
259 argument, or in the global variable
260 .IR _res ,
261 in the case of the older nonreentrant functions).
262 The only field of this structure that is normally manipulated by the
263 user is the
264 .IR options
265 field.
266 This field can contain the bitwise "OR"
267 of the following options:
268 .TP
269 .B RES_INIT
270 True if
271 .BR res_ninit ()
272 or
273 .BR res_init ()
274 has been called.
275 .TP
276 .B RES_DEBUG
277 Print debugging messages.
278 This option is available only if glibc was built with debugging enabled,
279 .\" See resolv/README.
280 .\" Support for RES_DEBUG was made conditional in glibc 2.2.
281 which is not the default.
282 .TP
283 .BR RES_AAONLY " (unimplemented; deprecated in glibc 2.25)"
284 Accept authoritative answers only.
285 .BR res_send ()
286 continues until
287 it finds an authoritative answer or returns an error.
288 This option was present but unimplemented in glibc until version 2.24;
289 since glibc 2.25, it is deprecated, and its usage produces a warning.
290 .TP
291 .B RES_USEVC
292 Use TCP connections for queries rather than UDP datagrams.
293 .TP
294 .BR RES_PRIMARY " (unimplemented; deprecated in glibc 2.25)"
295 Query primary domain name server only.
296 This option was present but unimplemented in glibc until version 2.24;
297 since glibc 2.25, it is deprecated, and its usage produces a warning.
298 .TP
299 .B RES_IGNTC
300 Ignore truncation errors.
301 Don't retry with TCP.
302 .TP
303 .B RES_RECURSE
304 Set the recursion desired bit in queries.
305 Recursion is carried out
306 by the domain name server, not by
307 .BR res_send ().
308 [Enabled by default].
309 .TP
310 .B RES_DEFNAMES
311 If set,
312 .BR res_search ()
313 will append the default domain name to
314 single component names\(emthat is, those that do not contain a dot.
315 [Enabled by default].
316 .TP
317 .B RES_STAYOPEN
318 Used with
319 .B RES_USEVC
320 to keep the TCP connection open between queries.
321 .TP
322 .B RES_DNSRCH
323 If set,
324 .BR res_search ()
325 will search for hostnames in the current
326 domain and in parent domains.
327 This option is used by
328 .BR gethostbyname (3).
329 [Enabled by default].
330 .TP
331 .B RES_INSECURE1
332 Accept a response from a wrong server.
333 This can be used to detect potential security hazards,
334 but you need to compile glibc with debugging enabled and use
335 .B RES_DEBUG
336 option (for debug purpose only).
337 .TP
338 .B RES_INSECURE2
339 Accept a response which contains a wrong query.
340 This can be used to detect potential security hazards,
341 but you need to compile glibc with debugging enabled and use
342 .B RES_DEBUG
343 option (for debug purpose only).
344 .TP
345 .B RES_NOALIASES
346 Disable usage of
347 .B HOSTALIASES
348 environment variable.
349 .TP
350 .B RES_USE_INET6
351 Try an AAAA query before an A query inside the
352 .BR gethostbyname (3)
353 function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records
354 are found but an A record set exists.
355 Since glibc 2.25, this option is deprecated,
356 and its usage produces a warning;
357 applications should use
358 .BR getaddrinfo (3),
359 rather than
360 .BR gethostbyname (3).
361 .TP
362 .B RES_ROTATE
363 Causes round-robin selection of name servers from among those listed.
364 This has the effect of spreading the query load among all listed servers,
365 rather than having all clients try the first listed server first every
366 time.
367 .TP
368 .BR RES_NOCHECKNAME " (unimplemented; deprecated in glibc 2.25)"
369 Disable the modern BIND checking of incoming hostnames and mail names
370 for invalid characters such as underscore (_), non-ASCII,
371 or control characters.
372 This option was present in glibc until version 2.24;
373 since glibc 2.25, it is deprecated, and its usage produces a warning.
374 .TP
375 .BR RES_KEEPTSIG " (unimplemented; deprecated in glibc 2.25)"
376 Do not strip TSIG records.
377 This option was present but unimplemented in glibc until version 2.24;
378 since glibc 2.25, it is deprecated, and its usage produces a warning.
379 .TP
380 .BR RES_BLAST " (unimplemented; deprecated in glibc 2.25)"
381 Send each query simultaneously and recursively to all servers.
382 This option was present but unimplemented in glibc until version 2.24;
383 since glibc 2.25, it is deprecated, and its usage produces a warning.
384 .TP
385 .BR RES_USEBSTRING " (glibc 2.3.4 to 2.24)"
386 Make reverse IPv6 lookups using the bit-label format described in RFC 2673;
387 if this option is not set (which is the default), then nibble format is used.
388 This option was removed in glibc 2.25,
389 since it relied on a backward-incompatible
390 DNS extension that was never deployed on the Internet.
391 .TP
392 .BR RES_NOIP6DOTINT " (glibc 2.24 and earlier)"
393 Use
394 .I ip6.arpa
395 zone in IPv6 reverse lookup instead of
396 .IR ip6.int ,
397 which is deprecated since glibc 2.3.4.
398 This option is present in glibc up to and including version 2.24,
399 where it is enabled by default.
400 In glibc 2.25, this option was removed.
401 .TP
402 .BR RES_USE_EDNS0 " (since glibc 2.6)"
403 Enables support for the DNS extensions (EDNS0) described in RFC 2671.
404 .TP
405 .BR RES_SNGLKUP " (since glibc 2.10)"
406 By default, glibc performs IPv4 and IPv6 lookups in parallel since
407 version 2.9.
408 Some appliance DNS servers cannot handle these queries properly
409 and make the requests time out.
410 This option disables the behavior and makes glibc
411 perform the IPv6 and IPv4 requests sequentially
412 (at the cost of some slowdown of the resolving process).
413 .TP
414 .B RES_SNGLKUPREOP
415 When
416 .B RES_SNGLKUP
417 option is enabled, opens a new socket for the each request.
418 .TP
419 .B RES_USE_DNSSEC
420 Use DNSSEC with OK bit in OPT record.
421 This option implies
422 .BR RES_USE_EDNS0 .
423 .TP
424 .B RES_NOTLDQUERY
425 Do not look up unqualified name as a top-level domain (TLD).
426 .TP
427 .B RES_DEFAULT
428 Default option which implies:
429 .BR RES_RECURSE ,
430 .BR RES_DEFNAMES ,
431 .BR RES_DNSRCH ,
432 and
433 .BR RES_NOIP6DOTINT .
434 .\"
435 .SH RETURN VALUE
436 The
437 .BR res_ninit ()
438 and
439 .BR res_init ()
440 functions return 0 on success, or \-1 if an error
441 occurs.
442 .PP
443 The
444 .BR res_nquery (),
445 .BR res_query (),
446 .BR res_nsearch (),
447 .BR res_search (),
448 .BR res_nquerydomain (),
449 .BR res_querydomain (),
450 .BR res_nmkquery (),
451 .BR res_mkquery (),
452 .BR res_nsend (),
453 and
454 .BR res_send ()
455 functions return the length
456 of the response, or \-1 if an error occurs.
457 .PP
458 The
459 .BR dn_comp ()
460 and
461 .BR dn_expand ()
462 functions return the length
463 of the compressed name, or \-1 if an error occurs.
464 .PP
465 In the case of an error return from
466 .BR res_nquery (),
467 .BR res_query (),
468 .BR res_nsearch (),
469 .BR res_search (),
470 .BR res_nquerydomain (),
471 or
472 .BR res_querydomain (),
473 the global variable
474 .I h_errno
475 (see
476 .BR gethostbyname (3))
477 can be consulted to determine the cause of the error.
478 .SH FILES
479 .TP
480 .I /etc/resolv.conf
481 resolver configuration file
482 .TP
483 .I /etc/host.conf
484 resolver configuration file
485 .SH ATTRIBUTES
486 For an explanation of the terms used in this section, see
487 .BR attributes (7).
488 .ad l
489 .nh
490 .TS
491 allbox;
492 lbx lb lb
493 l l l.
494 Interface Attribute Value
495 T{
496 .BR res_ninit (),
497 .BR res_nclose (),
498 .BR res_nquery (),
499 .BR res_nsearch (),
500 .BR res_nquerydomain (),
501 .BR res_nsend ()
502 T} Thread safety MT-Safe locale
503 T{
504 .BR res_nmkquery (),
505 .BR dn_comp (),
506 .BR dn_expand ()
507 T} Thread safety MT-Safe
508 .TE
509 .hy
510 .ad
511 .sp 1
512 .SH CONFORMING TO
513 4.3BSD.
514 .SH SEE ALSO
515 .BR gethostbyname (3),
516 .BR resolv.conf (5),
517 .BR resolver (5),
518 .BR hostname (7),
519 .BR named (8)
520 .PP
521 The GNU C library source file
522 .IR resolv/README .