1.\" $NetBSD: resolver.3,v 1.30 2016/01/22 10:58:39 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 January 22, 2016 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 stored in 221.Ft statp->options 222/ 223.Ft _res.options 224are defined in 225.Pa resolv.h 226and are as follows. 227Options are stored as a simple bit mask containing the bitwise 228.Dq OR 229of the options enabled. 230.Bl -tag -width "RES_USE_INET6" 231.It Dv RES_INIT 232True if the initial name server address and default domain name are 233initialized (i.e., 234.Fn res_ninit 235/ 236.Fn res_init 237has been called). 238.It Dv RES_DEBUG 239Print debugging messages. 240.It Dv RES_AAONLY 241Accept authoritative answers only. 242Should continue until it finds an authoritative answer or finds an error. 243Currently this is not implemented. 244.It Dv RES_USEVC 245Use TCP connections for queries instead of UDP datagrams. 246.It Dv RES_STAYOPEN 247Used with 248.Dv RES_USEVC 249to keep the TCP connection open between queries. 250This is useful only in programs that regularly do many queries. 251UDP should be the normal mode used. 252.It Dv RES_IGNTC 253Ignore truncation errors, i.e., don't retry with TCP. 254.It Dv RES_RECURSE 255Set the recursion-desired bit in queries. 256This is the default. 257(\c 258.Fn res_nsend 259/ 260.Fn res_send 261does not do iterative queries and expects the name server 262to handle recursion.) 263.It Dv RES_DEFNAMES 264If set, 265.Fn res_nsearch 266/ 267.Fn res_search 268will append the default domain name to single-component names 269(those that do not contain a dot). 270This option is enabled by default. 271.It Dv RES_DNSRCH 272If this option is set, 273.Fn res_nsearch 274/ 275.Fn res_search 276will search for host names in the current domain and in parent domains; see 277.Xr hostname 7 . 278This is used by the standard host lookup routine 279.Xr gethostbyname 3 . 280This option is enabled by default. 281.It Dv RES_USE_INET6 282Enables support for IPv6-only applications. 283This causes IPv4 addresses to be returned as an IPv4 mapped address. 284For example, 10.1.1.1 will be returned as ::ffff:10.1.1.1. 285The option is meaningful with certain kernel configuration only. 286.It Dv RES_USE_EDNS0 287Enables support for OPT pseudo-RR for EDNS0 extension. 288With the option, resolver code will attach OPT pseudo-RR into DNS queries, 289to inform of our receive buffer size. 290The option will allow DNS servers to take advantage of non-default receive 291buffer size, and to send larger replies. 292DNS query packets with EDNS0 extension is not compatible with 293non-EDNS0 DNS servers. 294.It Dv RES_NOALIASES 295This option turns off the user level aliasing feature controlled by 296the 297.Ev HOSTALIASES 298environment variable. 299Network daemons should set this option. 300.It Dv RES_ROTATE 301This options causes 302.Fn res_nsend 303/ 304.Fn res_send 305to rotate the list of nameservers in 306.Fa statp->nsaddr_list 307/ 308.Fa _res.nsaddr_list . 309.It Dv RES_KEEPTSIG 310This option causes 311.Fn res_nsendsigned 312to leave the message unchanged after TSIG verification; otherwise the TSIG 313record would be removed and the header updated. 314.It Dv RES_NOTLDQUERY 315This option causes 316.Fn res_nsearch 317to not attempt to resolve an unqualified name as if it were a top level 318domain (TLD). 319This option can cause problems if the site has "localhost" as a TLD rather 320than having localhost on one or more elements of the search list. 321This option has no effect if neither 322.Dv RES_DEFNAMES 323or 324.Dv RES_DNSRCH 325are set. 326.El 327.Pp 328The 329.Fn res_ninit 330/ 331.Fn res_init 332routines 333read the configuration file (if any; see 334.Xr resolv.conf 5 ) 335to get the default domain name, search list and 336the Internet address of the local name server(s). 337If no server is configured, the host running the resolver is tried. 338The current domain name is defined by the hostname 339if not specified in the configuration file; 340it can be overridden by the environment variable 341.Ev LOCALDOMAIN . 342This environment variable may contain several blank-separated 343tokens if you wish to override the 344.Fa search list 345on a per-process basis. 346This is similar to the 347.Fa search 348command in the configuration file. 349Another environment variable 350.Ev RES_OPTIONS 351can be set to override certain internal resolver options which are otherwise 352set by changing fields in the 353.Ft statp 354/ 355.Ft _res 356structure or are inherited from the configuration file's 357.Fa options 358command. 359The syntax of the 360.Ev RES_OPTIONS 361environment variable is explained in 362.Xr resolv.conf 5 . 363Initialization normally occurs on the first call 364to one of the other resolver routines. 365.Pp 366In 367.Nx 368the initialization code also sets up a 369.Xr kqueue 2 370and creates a 371.Xr kevent 2 372watching a file descriptor that points to the resolver file. 373Every resolver function calls the internal function 374.Fn __res_check 375which checks for a new 376.Xr kevent 2 377related to the 378.Xr resolv.conf 5 379file, and reloads the file if necessary. 380This does not work if the file is accessed through a symlink and the symlink 381changes to point to a different file. 382To fix the symlink issue one could add a system call per resolver call to 383get the current time, and reload every so often. 384This is not done currently, but it is under consideration. 385.Pp 386The memory referred to by 387.Ft statp 388must be set to all zeros prior to the first call to 389.Fn res_ninit . 390.Fn res_ndestroy 391should be called to free memory allocated by 392.Fn res_ninit 393after last use. 394.Pp 395The 396.Fn res_nquery 397/ 398.Fn res_query 399functions provide interfaces to the server query mechanism. 400They construct a query, send it to the local server, 401await a response, and make preliminary checks on the reply. 402The query requests information of the specified 403.Fa type 404and 405.Fa class 406for the specified fully-qualified domain name 407.Fa dname . 408The reply message is left in the 409.Fa answer 410buffer with length 411.Fa anslen 412supplied by the caller. 413.Fn res_nquery 414/ 415.Fn res_query 416return \-1 on error or the length of the answer. 417.Pp 418The 419.Fn res_nsearch 420/ 421.Fn res_search 422routines make a query and awaits a response like 423.Fn res_nquery 424/ 425.Fn res_query , 426but in addition, they implement the default and search rules 427controlled by the 428.Dv RES_DEFNAMES 429and 430.Dv RES_DNSRCH 431options. 432They return the length of the first successful reply which is stored in 433.Ft answer 434or \-1 on error. 435.Pp 436The remaining routines are lower-level routines used by 437.Fn res_nquery 438/ 439.Fn res_query . 440The 441.Fn res_nmkquery 442/ 443.Fn res_mkquery 444functions construct a standard query message and place it in 445.Fa buf . 446They return the size of the query, or \-1 if the query is 447larger than 448.Fa buflen . 449The query type 450.Fa op 451is usually 452.Dv QUERY , 453but can be any of the query types defined in 454.Aq Pa arpa/nameser.h . 455The domain name for the query is given by 456.Fa dname . 457.Fa newrr 458is currently unused but is intended for making update messages. 459.Pp 460The 461.Fn res_nsend 462/ 463.Fn res_send 464/ 465.Fn res_nsendsigned 466routines 467send a pre-formatted query and return an answer. 468They will call 469.Fn res_ninit 470/ 471.Fn res_init 472if 473.Dv RES_INIT 474is not set, send the query to the local name server, and 475handle timeouts and retries. 476Additionally, 477.Fn res_nsendsigned 478will use TSIG signatures to add authentication to the query and verify the 479response. 480In this case, only one nameserver will be contacted. 481The length of the reply message is returned, or \-1 if there were errors. 482.Pp 483.Fn res_nquery 484/ 485.Fn res_query , 486.Fn res_nsearch 487/ 488.Fn res_search 489and 490.Fn res_nsend 491/ 492.Fn res_send 493return a length that may be bigger than 494.Fa anslen . 495In that case the query should be retried with a bigger buffer. 496.Em NOTE : 497The answer to the second query may be larger still so supplying 498a buffer that bigger that the answer returned by the previous 499query is recommended. 500.Pp 501.Fa answer 502.Em MUST 503be 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 542look up name in the file referred to by the 543.Ev HOSTALIASES 544files and return a fully qualified hostname if found or 545.Dv NULL 546if not found or an error occurred. 547.Fn res_hostalias 548uses 549.Fa buf 550to store the result in, 551.Fn hostalias 552uses a static buffer. 553.Pp 554The functions 555.Fn res_getservers 556and 557.Fn res_setservers 558are used to get and set the list of server to be queried. 559.Pp 560The functions 561.Fn res_nupdate 562/ 563.Fn res_update 564take a list of ns_updrec 565.Fa rrecp_in . 566They identify the containing zone for each record and group the records 567according to containing zone maintaining in zone order then send an update 568request to the servers for these zones. 569The number of zones updated is returned or \-1 on error. 570Note that 571.Fn res_nupdate 572will perform TSIG authenticated dynamic update operations if the key is not 573.Dv NULL . 574.Pp 575The function 576.Fn res_findzonecut 577discovers the closest enclosing zone cut for a specified domain name, 578and finds the IP addresses of the zone's master servers. 579.Pp 580The functions 581.Fn res_nmkupdate 582/ 583.Fn res_mkupdate 584take a linked list of ns_updrec 585.Fa rrecp_in 586and construct an UPDATE message in 587.Fa buf . 588.Fn res_nmkupdate 589/ 590.Fn res_mkupdate 591return the length of the constructed message on no error or one of the 592following error values. 593.Bl -inset -width "-5" 594.It \-1 595An error occurred parsing 596.Fa rrecp_in . 597.It \-2 598The buffer 599.Fa buf 600was too small. 601.It \-3 602The first record was not a zone section or there was a section order problem. 603The section order is S_ZONE, S_PREREQ and S_UPDATE. 604.It \-4 605A number overflow occurred. 606.It \-5 607Unknown operation or no records. 608.El 609.Pp 610The functions 611.Fn res_nclose 612/ 613.Fn res_close 614close any open files referenced through 615.Fa statp 616/ 617.Fa _res . 618.Pp 619The function 620.Fn res_ndestroy 621calls 622.Fn res_nclose 623then frees any memory allocated by 624.Fn res_ninit . 625.Pp 626The 627.Fn dn_comp 628function 629compresses the domain name 630.Fa exp_dn 631and stores it in 632.Fa comp_dn . 633The size of the compressed name is returned or \-1 if there were errors. 634The size of the array pointed to by 635.Fa comp_dn 636is given by 637.Fa length . 638The compression uses 639an array of pointers 640.Fa dnptrs 641to previously-compressed names in the current message. 642The first pointer points to 643the beginning of the message and the list ends with 644.Dv NULL . 645The limit to the array is specified by 646.Fa lastdnptr . 647A side effect of 648.Fn dn_comp 649is to update the list of pointers for labels inserted into the message 650as the name is compressed. 651If 652.Fa dnptr 653is 654.Dv NULL , 655names are not compressed. 656If 657.Fa lastdnptr 658is 659.Dv NULL , 660the list of labels is not updated. 661.Pp 662The 663.Fn dn_expand 664entry expands the compressed domain name 665.Fa comp_dn 666to a full domain name. 667The compressed name is contained in a query or reply message; 668.Fa msg 669is a pointer to the beginning of the message. 670.Fa eomorig 671is a pointer to the first location after the message. 672The uncompressed name is placed in the buffer indicated by 673.Fa exp_dn 674which is of size 675.Fa length . 676The size of compressed name is returned or \-1 if there was an error. 677.Pp 678The variables 679.Ft statp->res_h_errno 680/ 681.Ft _res.res_h_errno 682and external variable 683.Ft h_errno 684are set whenever an error occurs during resolver operation. 685The following 686definitions are given in 687.Aq Pa netdb.h : 688.Bd -literal 689#define NETDB_INTERNAL -1 690/* see errno */ 691#define NETDB_SUCCESS 0 692/* no problem */ 693#define HOST_NOT_FOUND 1 694/* Authoritative Answer Host not found */ 695#define TRY_AGAIN 2 696/* Non-Authoritative not found, or SERVFAIL */ 697#define NO_RECOVERY 3 698/* Non-Recoverable: FORMERR, REFUSED, NOTIMP */ 699#define NO_DATA 4 700/* Valid name, no data for requested type */ 701.Ed 702.\" .Pp 703.\" The 704.\" .Fn herror 705.\" function writes a message to the diagnostic output consisting of the string 706.\" parameter 707.\" .Fa s , 708.\" the constant string ": ", and a message corresponding to the value of 709.\" .Ft h_errno . 710.\" .Pp 711.\" The 712.\" .Fn hstrerror 713.\" function returns a string which is the message text corresponding to the 714.\" value of the 715.\" .Fa err 716.\" parameter. 717.Pp 718The following functions are only in 719.Dv libresolv : 720.Fn res_findzonecut , 721.Fn res_nmkupdate , 722.Fn res_nsendsigned , 723and 724.Fn res_nupdate . 725All the rest are in both 726.Dv libc 727and 728.Dv libresolv . 729.Sh FILES 730.Bl -tag -width "/etc/resolv.conf " 731.It Pa /etc/resolv.conf 732The configuration file, see 733.Xr resolv.conf 5 . 734.El 735.Sh SEE ALSO 736.Xr getaddrinfo 3 , 737.Xr gethostbyaddr 3 , 738.Xr gethostbyname 3 , 739.Xr getnameinfo 3 , 740.Xr resolv.conf 5 , 741.Xr hostname 7 , 742.Xr named 8 743.Pp 744.%T RFC 974 , 745.%T RFC 1032 , 746.%T RFC 1033 , 747.%T RFC 1034 , 748.%T RFC 1035 , 749.%T RFC 1535 750.Rs 751.%T "Name Server Operations Guide for BIND" 752.Re 753.Sh HISTORY 754The 755.Nm 756function appeared in 757.Bx 4.3 . 758