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