1.\" $NetBSD: resolver.3,v 1.23 2009/10/02 06:49:23 cegger 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 181These routines are used for making, sending and interpreting 182query and reply messages with Internet domain name servers. 183.Pp 184State information is kept in 185.Fa statp 186and is used to control the behavior of these functions. 187.Fa statp 188should be set to all zeros prior to the first call to any of these functions. 189.Pp 190The 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 205are deprecated and are supplied for compatability with old source 206code. 207They use global configuration and state information that is 208kept in the structure 209.Ft _res 210rather than that referenced through 211.Ft statp . 212.Pp 213Most of the values in 214.Ft statp 215and 216.Ft _res 217are initialized on the first call to 218.Fn res_ninit 219/ 220.Fn res_init 221to reasonable defaults and can be ignored. 222Options 223stored in 224.Ft statp->options 225/ 226.Ft _res.options 227are defined in 228.Pa resolv.h 229and are as follows. 230Options are stored as a simple bit mask containing the bitwise 231.Dq OR 232of the options enabled. 233.Bl -tag -width "RES_USE_INET6" 234.It Dv RES_INIT 235True if the initial name server address and default domain name are 236initialized (i.e., 237.Fn res_ninit 238/ 239.Fn res_init 240has been called). 241.It Dv RES_DEBUG 242Print debugging messages. 243.It Dv RES_AAONLY 244Accept authoritative answers only. 245Should continue until it finds an authoritative answer or finds an error. 246Currently this is not implemented. 247.It Dv RES_USEVC 248Use TCP connections for queries instead of UDP datagrams. 249.It Dv RES_STAYOPEN 250Used with 251.Dv RES_USEVC 252to keep the TCP connection open between queries. 253This is useful only in programs that regularly do many queries. 254UDP should be the normal mode used. 255.It Dv RES_IGNTC 256Ignore truncation errors, i.e., don't retry with TCP. 257.It Dv RES_RECURSE 258Set the recursion-desired bit in queries. 259This is the default. 260(\c 261.Fn res_nsend 262/ 263.Fn res_send 264does not do iterative queries and expects the name server 265to handle recursion.) 266.It Dv RES_DEFNAMES 267If set, 268.Fn res_nsearch 269/ 270.Fn res_search 271will append the default domain name to single-component names 272(those that do not contain a dot). 273This option is enabled by default. 274.It Dv RES_DNSRCH 275If this option is set, 276.Fn res_nsearch 277/ 278.Fn res_search 279will search for host names in the current domain and in parent domains; see 280.Xr hostname 7 . 281This is used by the standard host lookup routine 282.Xr gethostbyname 3 . 283This option is enabled by default. 284.It Dv RES_USE_INET6 285Enables support for IPv6-only applications. 286This causes IPv4 addresses to be returned as an IPv4 mapped address. 287For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1. 288The option is meaningful with certain kernel configuration only. 289.It Dv RES_USE_EDNS0 290Enables support for OPT pseudo-RR for EDNS0 extension. 291With the option, resolver code will attach OPT pseudo-RR into DNS queries, 292to inform of our receive buffer size. 293The option will allow DNS servers to take advantage of non-default receive 294buffer size, and to send larger replies. 295DNS query packets with EDNS0 extension is not compatible with 296non-EDNS0 DNS servers. 297.It Dv RES_NOALIASES 298This option turns off the user level aliasing feature controlled by 299the 300.Ev HOSTALIASES 301environment variable. 302Network daemons should set this option. 303.It Dv RES_ROTATE 304This options causes the 305.Fn res_nsend 306/ 307.Fn res_send 308to rotate the list of nameservers in 309.Fa statp->nsaddr_list 310/ 311.Fa _res.nsaddr_list . 312.It Dv RES_KEEPTSIG 313This option causes 314.Fn res_nsendsigned 315to leave the message unchanged after TSIG verification; otherwise the TSIG 316record would be removed and the header updated. 317.It Dv RES_NOTLDQUERY 318This option causes 319.Fn res_nsearch 320to not attempt to resolve an unqualified name as if it were a top level 321domain (TLD). 322This option can cause problems if the site has "localhost" as a TLD rather 323than having localhost on one or more elements of the search list. 324This option has no effect if neither 325.Dv RES_DEFNAMES 326or 327.Dv RES_DNSRCH 328is set. 329.El 330.Pp 331The 332.Fn res_ninit 333/ 334.Fn res_init 335routine 336reads the configuration file (if any; see 337.Xr resolv.conf 5 ) 338to get the default domain name, search list and 339the Internet address of the local name server(s). 340If no server is configured, the host running the resolver is tried. 341The current domain name is defined by the hostname 342if not specified in the configuration file; 343it can be overridden by the environment variable 344.Ev LOCALDOMAIN . 345This environment variable may contain several blank-separated 346tokens if you wish to override the 347.Fa search list 348on a per-process basis. This is similar to the 349.Fa search 350command in the configuration file. 351Another environment variable 352.Ev RES_OPTIONS 353can be set to override certain internal resolver options which are otherwise 354set by changing fields in the 355.Ft statp 356/ 357.Ft _res 358structure or are inherited from the configuration file's 359.Fa options 360command. 361The syntax of the 362.Ev RES_OPTIONS 363environment variable is explained in 364.Xr resolv.conf 5 . 365Initialization normally occurs on the first call 366to one of the other resolver routines. 367.Pp 368The memory referred to by 369.Ft statp 370must be set to all zeros prior to the first call to 371.Fn res_ninit . 372.Fn res_ndestroy 373should be call to free memory allocated by 374.Fn res_ninit 375after last use. 376.Pp 377The 378.Fn res_nquery 379/ 380.Fn res_query 381functions provides interfaces to the server query mechanism. 382They constructs a query, sends it to the local server, 383awaits a response, and makes preliminary checks on the reply. 384The query requests information of the specified 385.Fa type 386and 387.Fa class 388for the specified fully-qualified domain name 389.Fa dname . 390The reply message is left in the 391.Fa answer 392buffer with length 393.Fa anslen 394supplied by the caller. 395.Fn res_nquery 396/ 397.Fn res_query 398return -1 on error or the length of the answer. 399.Pp 400The 401.Fn res_nsearch 402/ 403.Fn res_search 404routines make a query and awaits a response like 405.Fn res_nquery 406/ 407.Fn res_query , 408but in addition, it implements the default and search rules 409controlled by the 410.Dv RES_DEFNAMES 411and 412.Dv RES_DNSRCH 413options. 414It returns the length of the first successful reply which is stored in 415.Ft answer 416or -1 on error. 417.Pp 418The remaining routines are lower-level routines used by 419.Fn res_nquery 420/ 421.Fn res_query . 422The 423.Fn res_nmkquery 424/ 425.Fn res_mkquery 426functions 427constructs a standard query message and places it in 428.Fa buf . 429It returns the size of the query, or \-1 if the query is 430larger than 431.Fa buflen . 432The query type 433.Fa op 434is usually 435.Dv QUERY , 436but can be any of the query types defined in 437.Pa <arpa/nameser.h> . 438The domain name for the query is given by 439.Fa dname . 440.Fa newrr 441is currently unused but is intended for making update messages. 442.Pp 443The 444.Fn res_nsend 445/ 446.Fn res_send 447/ 448.Fn res_nsendsigned 449routines 450sends a pre-formatted query and returns an answer. 451It will call 452.Fn res_ninit 453/ 454.Fn res_init 455if 456.Dv RES_INIT 457is not set, send the query to the local name server, and 458handle timeouts and retries. Additionally, 459.Fn res_nsendsigned 460will use TSIG signatures to add authentication to the query and verify the 461response. In this case, only one nameserver will be contacted. 462The 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 470and 471.Fn res_nsend 472/ 473.Fn res_send 474return a length that may be bigger than 475.Fa anslen . 476In that case the query should be retried with a bigger buffer. 477NOTE the answer to the second query may be larger still so supplying 478a buffer that bigger that the answer returned by the previous 479query is recommended. 480.Pp 481.Fa answer 482MUST be big enough to receive a maximum UDP response from the server or 483parts of the answer will be silently discarded. 484The default maximum UDP response size is 512 bytes. 485.Pp 486The function 487.Fn res_ourserver_p 488returns true when 489.Fa inp 490is one of the servers in 491.Fa statp->nsaddr_list 492/ 493.Fa _res.nsaddr_list . 494.Pp 495The functions 496.Fn fp_nquery 497/ 498.Fn p_query 499print out the query and any answer in 500.Fa msg 501on 502.Fa fp . 503.Fn p_query 504is equivalent to 505.Fn fp_nquery 506with 507.Fa msglen 508set to 512. 509.Pp 510The function 511.Fn fp_resstat 512prints out the active flag bits in 513.Fa statp->options 514preceeded by the text ";; res options:" on 515.Fa file . 516.Pp 517The functions 518.Fn res_hostalias 519/ 520.Fn hostalias 521lookup up name in the file referred to by the 522.Ev HOSTALIASES 523files return a fully qualified hostname if found or NULL if 524not found or an error occurred. 525.Fn res_hostalias 526uses 527.Fa buf 528to store the result in, 529.Fn hostalias 530uses a static buffer. 531.Pp 532The functions 533.Fn res_getservers 534and 535.Fn res_setservers 536are used to get and set the list of server to be queried. 537.Pp 538The functions 539.Fn res_nupdate 540/ 541.Fn res_update 542take a list of ns_updrec 543.Fa rrecp_in . 544Identifies the containing zone for each record and groups the records 545according to containing zone maintaining in zone order then sends and update 546request to the servers for these zones. The number of zones updated is 547returned or -1 on error. Note that 548.Fn res_nupdate 549will perform TSIG authenticated dynamic update operations if the key is not 550NULL. 551.Pp 552The function 553.Fn res_findzonecut 554discovers the closest enclosing zone cut for a specified domain name, 555and finds the IP addresses of the zone's master servers. 556.Pp 557The functions 558.Fn res_nmkupdate 559/ 560.Fn res_mkupdate 561take a linked list of ns_updrec 562.Fa rrecp_in 563and construct a UPDATE message in 564.Fa buf . 565.Fn res_nmkupdate 566/ 567.Fn res_mkupdate 568return the length of the constructed message on no error or one of the 569following error values. 570.Bl -inset -width "-5" 571.It -1 572An error occurred parsing 573.Fa rrecp_in . 574.It -2 575The buffer 576.Fa buf 577was too small. 578.It -3 579The first record was not a zone section or there was a section order problem. 580The section order is S_ZONE, S_PREREQ and S_UPDATE. 581.It -4 582A number overflow occurred. 583.It -5 584Unknown operation or no records. 585.El 586.Pp 587The functions 588.Fn res_nclose 589/ 590.Fn res_close 591close any open files referenced through 592.Fa statp 593/ 594.Fa _res . 595.Pp 596The function 597.Fn res_ndestroy 598calls 599.Fn res_nclose 600then frees any memory allocated by 601.Fn res_ninit . 602.Pp 603The 604.Fn dn_comp 605function 606compresses the domain name 607.Fa exp_dn 608and stores it in 609.Fa comp_dn . 610The size of the compressed name is returned or \-1 if there were errors. 611The size of the array pointed to by 612.Fa comp_dn 613is given by 614.Fa length . 615The compression uses 616an array of pointers 617.Fa dnptrs 618to previously-compressed names in the current message. 619The first pointer points to 620the beginning of the message and the list ends with 621.Dv NULL . 622The limit to the array is specified by 623.Fa lastdnptr . 624A side effect of 625.Fn dn_comp 626is to update the list of pointers for labels inserted into the message 627as the name is compressed. If 628.Fa dnptr 629is 630.Dv NULL , 631names are not compressed. If 632.Fa lastdnptr 633is 634.Dv NULL , 635the list of labels is not updated. 636.Pp 637The 638.Fn dn_expand 639entry expands the compressed domain name 640.Fa comp_dn 641to a full domain name. 642The compressed name is contained in a query or reply message; 643.Fa msg 644is a pointer to the beginning of the message. 645.Fa eomorig 646is a pointer to the first location after the message. 647The uncompressed name is placed in the buffer indicated by 648.Fa exp_dn 649which is of size 650.Fa length . 651The size of compressed name is returned or \-1 if there was an error. 652.Pp 653The variables 654.Ft statp->res_h_errno 655/ 656.Ft _res.res_h_errno 657and external variable 658.Ft h_errno 659is set whenever an error occurs during resolver operation. The following 660definitions 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 695The 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 714The 715.Nm 716function appeared in 717.Bx 4.3 . 718