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