| blob | 724a6beffdeb4e679abae59713bedbdb5933b73e |
1 .\" $NetBSD: resolver.3,v 1.22 2009/06/08 16:55:30 christos Exp $
2 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
3 .\"
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
14 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .\" Copyright (c) 1985, 1995 The Regents of the University of California.
17 .\" All rights reserved.
18 .\"
19 .\" Redistribution and use in source and binary forms are permitted provided
20 .\" that: (1) source distributions retain this entire copyright notice and
21 .\" comment, and (2) distributions including binaries display the following
22 .\" acknowledgement: ``This product includes software developed by the
23 .\" University of California, Berkeley and its contributors'' in the
24 .\" documentation or other materials provided with the distribution and in
25 .\" all advertising materials mentioning features or use of this software.
26 .\" Neither the name of the University nor the names of its contributors may
27 .\" be used to endorse or promote products derived from this software without
28 .\" specific prior written permission.
29 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
30 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
31 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
32 .\"
33 .\" @(#)resolver.3 6.5 (Berkeley) 6/23/90
34 .\" Id: resolver.man3,v 1.2 2009/01/21 00:12:34 each Exp
35 .\"
36 .Dd July 4, 2000
37 .Dt RESOLVER 3
38 .Os
39 .Sh NAME
40 .Nm res_ninit ,
41 .Nm res_ourserver_p ,
42 .Nm fp_resstat ,
43 .Nm res_hostalias ,
44 .Nm res_pquery ,
45 .Nm res_nquery ,
46 .Nm res_nsearch ,
47 .Nm res_nquerydomain ,
48 .Nm res_nmkquery ,
49 .Nm res_nsend ,
50 .Nm res_nupdate ,
51 .Nm res_nmkupdate ,
52 .Nm res_nclose ,
53 .Nm res_nsendsigned ,
54 .Nm res_findzonecut ,
55 .Nm res_getservers ,
56 .Nm res_setservers ,
57 .Nm res_ndestroy ,
58 .Nm dn_comp ,
59 .Nm dn_expand ,
60 .\" .Nm hstrerror ,
61 .Nm res_init ,
62 .Nm res_isourserver ,
63 .Nm fp_nquery ,
64 .Nm p_query ,
65 .Nm hostalias ,
66 .Nm res_query ,
67 .Nm res_search ,
68 .Nm res_querydomain ,
69 .Nm res_mkquery ,
70 .Nm res_send ,
71 .Nm res_update ,
72 .Nm res_close ,
73 .\" .Nm herror
74 .Nd resolver routines
75 .Sh LIBRARY
76 .Lb libc
77 .Sh SYNOPSIS
78 .In sys/types.h
79 .In netinet/in.h
80 .In arpa/nameser.h
81 .In resolv.h
82 .In res_update.h
83 .Vt typedef struct __res_state *res_state ;
84 .Pp
85 .Ft int
86 .Fn res_ninit "res_state statp"
87 .Ft int
88 .Fn res_ourserver_p "const res_state statp" "const struct sockaddr_in *addr"
89 .Ft void
90 .Fn fp_resstat "const res_state statp" "FILE *fp"
91 .Ft "const char *"
92 .Fn res_hostalias "const res_state statp" "const char *name" "char *buf" "size_t buflen"
93 .Ft int
94 .Fn res_pquery "const res_state statp" "const u_char *msg" "int msglen" "FILE *fp"
95 .Ft int
96 .Fn res_nquery "res_state statp" "const char *dname" "int class" "int type" "u_char *answer" "int anslen"
97 .Ft int
98 .Fn res_nsearch "res_state statp" "const char *dname" "int class" "int type" "u_char * answer" "int anslen"
99 .Ft int
100 .Fn res_nquerydomain "res_state statp" "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen"
101 .Ft int
102 .Fo res_nmkquery
103 .Fa "res_state statp"
104 .Fa "int op"
105 .Fa "const char *dname"
106 .Fa "int class"
107 .Fa "int type"
108 .Fa "const u_char *data"
109 .Fa "int datalen"
110 .Fa "const u_char *newrr"
111 .Fa "u_char *buf"
112 .Fa "int buflen"
113 .Fc
114 .Ft int
115 .Fn res_nsend "res_state statp" "const u_char *msg" "int msglen" "u_char *answer" "int anslen"
116 .Ft int
117 .Fn res_nupdate "res_state statp" "ns_updrec *rrecp_in"
118 .Ft int
119 .Fn res_nmkupdate "res_state statp" "ns_updrec *rrecp_in" "u_char *buf" "int buflen"
120 .Ft void
121 .Fn res_nclose "res_state statp"
122 .Ft int
123 .Fn res_nsendsigned "res_state statp" "const u_char *msg" "int msglen" "ns_tsig_key *key" "u_char *answer" "int anslen"
124 .Ft int
125 .Fn res_findzonecut "res_state statp" "const char *dname" "ns_class class" "int options" "char *zname" "size_t zsize" "struct in_addr *addrs" "int naddrs"
126 .Ft int
127 .Fn res_getservers "res_state statp" "union res_sockaddr_union *set" "int cnt"
128 .Ft void
129 .Fn res_setservers "res_state statp" "const union res_sockaddr_union *set" "int cnt"
130 .Ft void
131 .Fn res_ndestroy "res_state statp"
132 .Ft int
133 .Fn dn_comp "const char *exp_dn" "u_char *comp_dn" "int length" "u_char **dnptrs" "u_char **lastdnptr"
134 .Ft int
135 .Fn dn_expand "const u_char *msg" "const u_char *eomorig" "const u_char *comp_dn" "char *exp_dn" "int length"
136 .\" .Ft "const char *"
137 .\" .Fn hstrerror "int err"
138 .Ss DEPRECATED
139 .In sys/types.h
140 .In netinet/in.h
141 .In arpa/nameser.h
142 .In resolv.h
143 .In res_update.h
144 .Ft int
145 .Fn res_init "void"
146 .Ft int
147 .Fn res_isourserver "const struct sockaddr_in *addr"
148 .Ft int
149 .Fn fp_nquery "const u_char *msg" "int msglen" "FILE *fp"
150 .Ft void
151 .Fn p_query "const u_char *msg" "FILE *fp"
152 .Ft "const char *"
153 .Fn hostalias "const char *name"
154 .Ft int
155 .Fn res_query "const char *dname" "int class" "int type" "u_char *answer" "int anslen"
156 .Ft int
157 .Fn res_search "const char *dname" "int class" "int type" "u_char *answer" "int anslen"
158 .Ft int
159 .Fn res_querydomain "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen"
160 .Ft int
161 .Fo res_mkquery
162 .Fa "int op"
163 .Fa "const char *dname"
164 .Fa "int class"
165 .Fa "int type"
166 .Fa "const char *data"
167 .Fa "int datalen"
168 .Fa "struct rrec *newrr"
169 .Fa "u_char *buf"
170 .Fa "int buflen"
171 .Fc
172 .Ft int
173 .Fn res_send "const u_char *msg" "int msglen" "u_char *answer" "int anslen"
174 .Ft int
175 .Fn res_update "ns_updrec *rrecp_in"
176 .Ft void
177 .Fn res_close "void"
178 .\" .Ft void
179 .\" .Fn herror "const char *s"
180 .Sh DESCRIPTION
181 These routines are used for making, sending and interpreting
182 query and reply messages with Internet domain name servers.
183 .Pp
184 State information is kept in
185 .Fa statp
186 and is used to control the behavior of these functions.
187 .Fa statp
188 should be set to all zeros prior to the first call to any of these functions.
189 .Pp
190 The functions
191 .Fn res_init ,
192 .Fn res_isourserver ,
193 .Fn fp_nquery ,
194 .Fn p_query ,
195 .Fn hostalias ,
196 .Fn res_query ,
197 .Fn res_search ,
198 .Fn res_querydomain ,
199 .Fn res_mkquery ,
200 .Fn res_send ,
201 .Fn res_update ,
202 .Fn res_close
203 .\" and
204 .\" .Fn herror
205 are deprecated and are supplied for compatability with old source
206 code.
207 They use global configuration and state information that is
208 kept in the structure
209 .Ft _res
210 rather than that referenced through
211 .Ft statp .
212 .Pp
213 Most of the values in
214 .Ft statp
215 and
216 .Ft _res
217 are initialized on the first call to
218 .Fn res_ninit
219 /
220 .Fn res_init
221 to reasonable defaults and can be ignored.
222 Options
223 stored in
224 .Ft statp->options
225 /
226 .Ft _res.options
227 are defined in
228 .Pa resolv.h
229 and are as follows.
230 Options are stored as a simple bit mask containing the bitwise
231 .Dq OR
232 of the options enabled.
233 .Bl -tag -width "RES_USE_INET6"
234 .It Dv RES_INIT
235 True if the initial name server address and default domain name are
236 initialized (i.e.,
237 .Fn res_ninit
238 /
239 .Fn res_init
240 has been called).
241 .It Dv RES_DEBUG
242 Print debugging messages.
243 .It Dv RES_AAONLY
244 Accept authoritative answers only.
245 Should continue until it finds an authoritative answer or finds an error.
246 Currently this is not implemented.
247 .It Dv RES_USEVC
248 Use TCP connections for queries instead of UDP datagrams.
249 .It Dv RES_STAYOPEN
250 Used with
251 .Dv RES_USEVC
252 to keep the TCP connection open between queries.
253 This is useful only in programs that regularly do many queries.
254 UDP should be the normal mode used.
255 .It Dv RES_IGNTC
256 Ignore truncation errors, i.e., don't retry with TCP.
257 .It Dv RES_RECURSE
258 Set the recursion-desired bit in queries.
259 This is the default.
260 (\c
261 .Fn res_nsend
262 /
263 .Fn res_send
264 does not do iterative queries and expects the name server
265 to handle recursion.)
266 .It Dv RES_DEFNAMES
267 If set,
268 .Fn res_nsearch
269 /
270 .Fn res_search
271 will append the default domain name to single-component names
272 (those that do not contain a dot).
273 This option is enabled by default.
274 .It Dv RES_DNSRCH
275 If this option is set,
276 .Fn res_nsearch
277 /
278 .Fn res_search
279 will search for host names in the current domain and in parent domains; see
280 .Xr hostname 7 .
281 This is used by the standard host lookup routine
282 .Xr gethostbyname 3 .
283 This option is enabled by default.
284 .It Dv RES_USE_INET6
285 Enables support for IPv6-only applications.
286 This causes IPv4 addresses to be returned as an IPv4 mapped address.
287 For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1.
288 The option is meaningful with certain kernel configuration only.
289 .It Dv RES_USE_EDNS0
290 Enables support for OPT pseudo-RR for EDNS0 extension.
291 With the option, resolver code will attach OPT pseudo-RR into DNS queries,
292 to inform of our receive buffer size.
293 The option will allow DNS servers to take advantage of non-default receive
294 buffer size, and to send larger replies.
295 DNS query packets with EDNS0 extension is not compatible with
296 non-EDNS0 DNS servers.
297 .It Dv RES_NOALIASES
298 This option turns off the user level aliasing feature controlled by
299 the
300 .Ev HOSTALIASES
301 environment variable.
302 Network daemons should set this option.
303 .It Dv RES_ROTATE
304 This options causes the
305 .Fn res_nsend
306 /
307 .Fn res_send
308 to rotate the list of nameservers in
309 .Fa statp->nsaddr_list
310 /
311 .Fa _res.nsaddr_list .
312 .It Dv RES_KEEPTSIG
313 This option causes
314 .Fn res_nsendsigned
315 to leave the message unchanged after TSIG verification; otherwise the TSIG
316 record would be removed and the header updated.
317 .It Dv RES_NOTLDQUERY
318 This option causes
319 .Fn res_nsearch
320 to not attempt to resolve an unqualified name as if it were a top level
321 domain (TLD).
322 This option can cause problems if the site has "localhost" as a TLD rather
323 than having localhost on one or more elements of the search list.
324 This option has no effect if neither
325 .Dv RES_DEFNAMES
326 or
327 .Dv RES_DNSRCH
328 is set.
329 .El
330 .Pp
331 The
332 .Fn res_ninit
333 /
334 .Fn res_init
335 routine
336 reads the configuration file (if any; see
337 .Xr resolv.conf 5 )
338 to get the default domain name, search list and
339 the Internet address of the local name server(s).
340 If no server is configured, the host running the resolver is tried.
341 The current domain name is defined by the hostname
342 if not specified in the configuration file;
343 it can be overridden by the environment variable
344 .Ev LOCALDOMAIN .
345 This environment variable may contain several blank-separated
346 tokens if you wish to override the
347 .Fa search list
348 on a per-process basis. This is similar to the
349 .Fa search
350 command in the configuration file.
351 Another environment variable
352 .Ev RES_OPTIONS
353 can be set to override certain internal resolver options which are otherwise
354 set by changing fields in the
355 .Ft statp
356 /
357 .Ft _res
358 structure or are inherited from the configuration file's
359 .Fa options
360 command.
361 The syntax of the
362 .Ev RES_OPTIONS
363 environment variable is explained in
364 .Xr resolv.conf 5 .
365 Initialization normally occurs on the first call
366 to one of the other resolver routines.
367 .Pp
368 The memory referred to by
369 .Ft statp
370 must be set to all zeros prior to the first call to
371 .Fn res_ninit .
372 .Fn res_ndestroy
373 should be call to free memory allocated by
374 .Fn res_ninit
375 after last use.
376 .Pp
377 The
378 .Fn res_nquery
379 /
380 .Fn res_query
381 functions provides interfaces to the server query mechanism.
382 They constructs a query, sends it to the local server,
383 awaits a response, and makes preliminary checks on the reply.
384 The query requests information of the specified
385 .Fa type
386 and
387 .Fa class
388 for the specified fully-qualified domain name
389 .Fa dname .
390 The reply message is left in the
391 .Fa answer
392 buffer with length
393 .Fa anslen
394 supplied by the caller.
395 .Fn res_nquery
396 /
397 .Fn res_query
398 return -1 on error or the length of the answer.
399 .Pp
400 The
401 .Fn res_nsearch
402 /
403 .Fn res_search
404 routines make a query and awaits a response like
405 .Fn res_nquery
406 /
407 .Fn res_query ,
408 but in addition, it implements the default and search rules
409 controlled by the
410 .Dv RES_DEFNAMES
411 and
412 .Dv RES_DNSRCH
413 options.
414 It returns the length of the first successful reply which is stored in
415 .Ft answer
416 or -1 on error.
417 .Pp
418 The remaining routines are lower-level routines used by
419 .Fn res_nquery
420 /
421 .Fn res_query .
422 The
423 .Fn res_nmkquery
424 /
425 .Fn res_mkquery
426 functions
427 constructs a standard query message and places it in
428 .Fa buf .
429 It returns the size of the query, or \-1 if the query is
430 larger than
431 .Fa buflen .
432 The query type
433 .Fa op
434 is usually
435 .Dv QUERY ,
436 but can be any of the query types defined in
437 .Pa <arpa/nameser.h> .
438 The domain name for the query is given by
439 .Fa dname .
440 .Fa newrr
441 is currently unused but is intended for making update messages.
442 .Pp
443 The
444 .Fn res_nsend
445 /
446 .Fn res_send
447 /
448 .Fn res_nsendsigned
449 routines
450 sends a pre-formatted query and returns an answer.
451 It will call
452 .Fn res_ninit
453 /
454 .Fn res_init
455 if
456 .Dv RES_INIT
457 is not set, send the query to the local name server, and
458 handle timeouts and retries. Additionally,
459 .Fn res_nsendsigned
460 will use TSIG signatures to add authentication to the query and verify the
461 response. In this case, only one nameserver will be contacted.
462 The length of the reply message is returned, or \-1 if there were errors.
463 .Pp
464 .Fn res_nquery
465 /
466 .Fn res_query ,
467 .Fn res_nsearch
468 /
469 .Fn res_search
470 and
471 .Fn res_nsend
472 /
473 .Fn res_send
474 return a length that may be bigger than
475 .Fa anslen .
476 In that case the query should be retried with a bigger buffer.
477 NOTE the answer to the second query may be larger still so supplying
478 a buffer that bigger that the answer returned by the previous
479 query is recommended.
480 .Pp
481 .Fa answer
482 MUST be big enough to receive a maximum UDP response from the server or
483 parts of the answer will be silently discarded.
484 The default maximum UDP response size is 512 bytes.
485 .Pp
486 The function
487 .Fn res_ourserver_p
488 returns true when
489 .Fa inp
490 is one of the servers in
491 .Fa statp->nsaddr_list
492 /
493 .Fa _res.nsaddr_list .
494 .Pp
495 The functions
496 .Fn fp_nquery
497 /
498 .Fn p_query
499 print out the query and any answer in
500 .Fa msg
501 on
502 .Fa fp .
503 .Fn p_query
504 is equivalent to
505 .Fn fp_nquery
506 with
507 .Fa msglen
508 set to 512.
509 .Pp
510 The function
511 .Fn fp_resstat
512 prints out the active flag bits in
513 .Fa statp->options
514 preceeded by the text ";; res options:" on
515 .Fa file .
516 .Pp
517 The functions
518 .Fn res_hostalias
519 /
520 .Fn hostalias
521 lookup up name in the file referred to by the
522 .Ev HOSTALIASES
523 files return a fully qualified hostname if found or NULL if
524 not found or an error occurred.
525 .Fn res_hostalias
526 uses
527 .Fa buf
528 to store the result in,
529 .Fn hostalias
530 uses a static buffer.
531 .Pp
532 The functions
533 .Fn res_getservers
534 and
535 .Fn res_setservers
536 are used to get and set the list of server to be queried.
537 .Pp
538 The functions
539 .Fn res_nupdate
540 /
541 .Fn res_update
542 take a list of ns_updrec
543 .Fa rrecp_in .
544 Identifies the containing zone for each record and groups the records
545 according to containing zone maintaining in zone order then sends and update
546 request to the servers for these zones. The number of zones updated is
547 returned or -1 on error. Note that
548 .Fn res_nupdate
549 will perform TSIG authenticated dynamic update operations if the key is not
550 NULL.
551 .Pp
552 The function
553 .Fn res_findzonecut
554 discovers the closest enclosing zone cut for a specified domain name,
555 and finds the IP addresses of the zone's master servers.
556 .Pp
557 The functions
558 .Fn res_nmkupdate
559 /
560 .Fn res_mkupdate
561 take a linked list of ns_updrec
562 .Fa rrecp_in
563 and construct a UPDATE message in
564 .Fa buf .
565 .Fn res_nmkupdate
566 /
567 .Fn res_mkupdate
568 return the length of the constructed message on no error or one of the
569 following error values.
570 .Bl -inset -width "-5"
571 .It -1
572 An error occurred parsing
573 .Fa rrecp_in .
574 .It -2
575 The buffer
576 .Fa buf
577 was too small.
578 .It -3
579 The first record was not a zone section or there was a section order problem.
580 The section order is S_ZONE, S_PREREQ and S_UPDATE.
581 .It -4
582 A number overflow occurred.
583 .It -5
584 Unknown operation or no records.
585 .El
586 .Pp
587 The functions
588 .Fn res_nclose
589 /
590 .Fn res_close
591 close any open files referenced through
592 .Fa statp
593 /
594 .Fa _res .
595 .Pp
596 The function
597 .Fn res_ndestroy
598 calls
599 .Fn res_nclose
600 then frees any memory allocated by
601 .Fn res_ninit .
602 .Pp
603 The
604 .Fn dn_comp
605 function
606 compresses the domain name
607 .Fa exp_dn
608 and stores it in
609 .Fa comp_dn .
610 The size of the compressed name is returned or \-1 if there were errors.
611 The size of the array pointed to by
612 .Fa comp_dn
613 is given by
614 .Fa length .
615 The compression uses
616 an array of pointers
617 .Fa dnptrs
618 to previously-compressed names in the current message.
619 The first pointer points to
620 the beginning of the message and the list ends with
621 .Dv NULL .
622 The limit to the array is specified by
623 .Fa lastdnptr .
624 A side effect of
625 .Fn dn_comp
626 is to update the list of pointers for labels inserted into the message
627 as the name is compressed. If
628 .Fa dnptr
629 is
630 .Dv NULL ,
631 names are not compressed. If
632 .Fa lastdnptr
633 is
634 .Dv NULL ,
635 the list of labels is not updated.
636 .Pp
637 The
638 .Fn dn_expand
639 entry expands the compressed domain name
640 .Fa comp_dn
641 to a full domain name.
642 The compressed name is contained in a query or reply message;
643 .Fa msg
644 is a pointer to the beginning of the message.
645 .Fa eomorig
646 is a pointer to the first location after the message.
647 The uncompressed name is placed in the buffer indicated by
648 .Fa exp_dn
649 which is of size
650 .Fa length .
651 The size of compressed name is returned or \-1 if there was an error.
652 .Pp
653 The variables
654 .Ft statp->res_h_errno
655 /
656 .Ft _res.res_h_errno
657 and external variable
658 .Ft h_errno
659 is set whenever an error occurs during resolver operation. The following
660 definitions are given in
661 .Pa <netdb.h> :
662 .Bd -literal
663 #define NETDB_INTERNAL -1
664 /* see errno */
665 #define NETDB_SUCCESS 0
666 /* no problem */
667 #define HOST_NOT_FOUND 1
668 /* Authoritative Answer Host not found */
669 #define TRY_AGAIN 2
670 /* Non-Authoritative not found, or SERVFAIL */
671 #define NO_RECOVERY 3
672 /* Non-Recoverable: FORMERR, REFUSED, NOTIMP */
673 #define NO_DATA 4
674 /* Valid name, no data for requested type */
675 .Ed
676 .\" .Pp
677 .\" The
678 .\" .Fn herror
679 .\" function writes a message to the diagnostic output consisting of the string
680 .\" parameter
681 .\" .Fa s ,
682 .\" the constant string ": ", and a message corresponding to the value of
683 .\" .Ft h_errno .
684 .\" .Pp
685 .\" The
686 .\" .Fn hstrerror
687 .\" function returns a string which is the message text corresponding to the
688 .\" value of the
689 .\" .Fa err
690 .\" parameter.
691 .Sh FILES
692 .Bl -tag -width "/etc/resolv.conf "
693 .It Pa
694 /etc/resolv.conf
695 The configuration file, see
696 .Xr resolv.conf 5 .
697 .El
698 .Sh SEE ALSO
699 .Xr gethostbyname 3 ,
700 .Xr hostname 7 ,
701 .Xr resolv.conf 5 ,
702 .Xr named 8
703 .Pp
704 .%T RFC 974 ,
705 .%T RFC 1032 ,
706 .%T RFC 1033 ,
707 .%T RFC 1034 ,
708 .%T RFC 1035 ,
709 .%T RFC 1535
710 .Rs
711 .%T "Name Server Operations Guide for BIND"
712 .Re
713 .Sh HISTORY
714 The
715 .Nm
716 function appeared in
717 .Bx 4.3 .