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