1.\" Copyright (c) 1985, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)resolver.3 8.1 (Berkeley) 6/4/93 29.\" $FreeBSD$ 30.\" 31.Dd November 4, 2006 32.Dt RESOLVER 3 33.Os 34.Sh NAME 35.Nm res_query , 36.Nm res_search , 37.Nm res_mkquery , 38.Nm res_send , 39.Nm res_init , 40.Nm dn_comp , 41.Nm dn_expand , 42.Nm dn_skipname , 43.Nm ns_get16 , 44.Nm ns_get32 , 45.Nm ns_put16 , 46.Nm ns_put32 47.Nd resolver routines 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.In sys/types.h 52.In netinet/in.h 53.In arpa/nameser.h 54.In resolv.h 55.Ft int 56.Fo res_query 57.Fa "const char *dname" 58.Fa "int class" 59.Fa "int type" 60.Fa "u_char *answer" 61.Fa "int anslen" 62.Fc 63.Ft int 64.Fo res_search 65.Fa "const char *dname" 66.Fa "int class" 67.Fa "int type" 68.Fa "u_char *answer" 69.Fa "int anslen" 70.Fc 71.Ft int 72.Fo res_mkquery 73.Fa "int op" 74.Fa "const char *dname" 75.Fa "int class" 76.Fa "int type" 77.Fa "const u_char *data" 78.Fa "int datalen" 79.Fa "const u_char *newrr_in" 80.Fa "u_char *buf" 81.Fa "int buflen" 82.Fc 83.Ft int 84.Fo res_send 85.Fa "const u_char *msg" 86.Fa "int msglen" 87.Fa "u_char *answer" 88.Fa "int anslen" 89.Fc 90.Ft int 91.Fn res_init void 92.Ft int 93.Fo dn_comp 94.Fa "const char *exp_dn" 95.Fa "u_char *comp_dn" 96.Fa "int length" 97.Fa "u_char **dnptrs" 98.Fa "u_char **lastdnptr" 99.Fc 100.Ft int 101.Fo dn_expand 102.Fa "const u_char *msg" 103.Fa "const u_char *eomorig" 104.Fa "const u_char *comp_dn" 105.Fa "char *exp_dn" 106.Fa "int length" 107.Fc 108.Ft int 109.Fn dn_skipname "const u_char *comp_dn" "const u_char *eom" 110.Ft u_int 111.Fn ns_get16 "const u_char *src" 112.Ft u_long 113.Fn ns_get32 "const u_char *src" 114.Ft void 115.Fn ns_put16 "u_int src" "u_char *dst" 116.Ft void 117.Fn ns_put32 "u_long src" "u_char *dst" 118.Sh DESCRIPTION 119These routines are used for making, sending and interpreting 120query and reply messages with Internet domain name servers. 121.Pp 122Global configuration and state information that is used by the 123resolver routines is kept in the structure 124.Va _res . 125Most of the values have reasonable defaults and can be ignored. 126Options 127stored in 128.Va _res.options 129are defined in 130.In resolv.h 131and are as follows. 132Options are stored as a simple bit mask containing the bitwise ``or'' 133of the options enabled. 134.Bl -tag -width RES_USE_INET6 135.It Dv RES_INIT 136True if the initial name server address and default domain name are 137initialized (i.e., 138.Fn res_init 139has been called). 140.It Dv RES_DEBUG 141Print debugging messages. 142.It Dv RES_AAONLY 143Accept authoritative answers only. 144With this option, 145.Fn res_send 146should continue until it finds an authoritative answer or finds an error. 147Currently this is not implemented. 148.It Dv RES_USEVC 149Use 150.Tn TCP 151connections for queries instead of 152.Tn UDP 153datagrams. 154.It Dv RES_STAYOPEN 155Used with 156.Dv RES_USEVC 157to keep the 158.Tn TCP 159connection open between 160queries. 161This is useful only in programs that regularly do many queries. 162.Tn UDP 163should be the normal mode used. 164.It Dv RES_IGNTC 165Unused currently (ignore truncation errors, i.e., do not retry with 166.Tn TCP ) . 167.It Dv RES_RECURSE 168Set the recursion-desired bit in queries. 169This is the default. 170.Pf ( Fn res_send 171does not do iterative queries and expects the name server 172to handle recursion.) 173.It Dv RES_DEFNAMES 174If set, 175.Fn res_search 176will append the default domain name to single-component names 177(those that do not contain a dot). 178This option is enabled by default. 179.It Dv RES_DNSRCH 180If this option is set, 181.Fn res_search 182will search for host names in the current domain and in parent domains; see 183.Xr hostname 7 . 184This is used by the standard host lookup routine 185.Xr gethostbyname 3 . 186This option is enabled by default. 187.It Dv RES_NOALIASES 188This option turns off the user level aliasing feature controlled by the 189.Dq Ev HOSTALIASES 190environment variable. 191Network daemons should set this option. 192.It Dv RES_USE_INET6 193Enables support for IPv6-only applications. 194This causes IPv4 addresses to be returned as an IPv4 mapped address. 195For example, 196.Li 10.1.1.1 197will be returned as 198.Li ::ffff:10.1.1.1 . 199The option is meaningful with certain kernel configuration only. 200.It Dv RES_USE_EDNS0 201Enables support for OPT pseudo-RR for EDNS0 extension. 202With the option, resolver code will attach OPT pseudo-RR into DNS queries, 203to inform of our receive buffer size. 204The option will allow DNS servers to take advantage of non-default receive 205buffer size, and to send larger replies. 206DNS query packets with EDNS0 extension is not compatible with 207non-EDNS0 DNS servers. 208.El 209.Pp 210The 211.Fn res_init 212routine 213reads the configuration file (if any; see 214.Xr resolver 5 ) 215to get the default domain name, 216search list and 217the Internet address of the local name server(s). 218If no server is configured, the host running 219the resolver is tried. 220The current domain name is defined by the hostname 221if not specified in the configuration file; 222it can be overridden by the environment variable 223.Ev LOCALDOMAIN . 224This environment variable may contain several blank-separated 225tokens if you wish to override the 226.Em "search list" 227on a per-process basis. 228This is similar to the 229.Ic search 230command in the configuration file. 231Another environment variable 232.Dq Ev RES_OPTIONS 233can be set to 234override certain internal resolver options which are otherwise 235set by changing fields in the 236.Va _res 237structure or are inherited from the configuration file's 238.Ic options 239command. 240The syntax of the 241.Dq Ev RES_OPTIONS 242environment variable is explained in 243.Xr resolver 5 . 244Initialization normally occurs on the first call 245to one of the following routines. 246.Pp 247The 248.Fn res_query 249function provides an interface to the server query mechanism. 250It constructs a query, sends it to the local server, 251awaits a response, and makes preliminary checks on the reply. 252The query requests information of the specified 253.Fa type 254and 255.Fa class 256for the specified fully-qualified domain name 257.Fa dname . 258The reply message is left in the 259.Fa answer 260buffer with length 261.Fa anslen 262supplied by the caller. 263.Pp 264The 265.Fn res_search 266routine makes a query and awaits a response like 267.Fn res_query , 268but in addition, it implements the default and search rules 269controlled by the 270.Dv RES_DEFNAMES 271and 272.Dv RES_DNSRCH 273options. 274It returns the first successful reply. 275.Pp 276The remaining routines are lower-level routines used by 277.Fn res_query . 278The 279.Fn res_mkquery 280function 281constructs a standard query message and places it in 282.Fa buf . 283It returns the size of the query, or \-1 if the query is 284larger than 285.Fa buflen . 286The query type 287.Fa op 288is usually 289.Dv QUERY , 290but can be any of the query types defined in 291.In arpa/nameser.h . 292The domain name for the query is given by 293.Fa dname . 294The 295.Fa newrr_in 296argument 297is currently unused but is intended for making update messages. 298.Pp 299The 300.Fn res_send 301routine 302sends a pre-formatted query and returns an answer. 303It will call 304.Fn res_init 305if 306.Dv RES_INIT 307is not set, send the query to the local name server, and 308handle timeouts and retries. 309The length of the reply message is returned, or 310\-1 if there were errors. 311.Pp 312The 313.Fn dn_comp 314function 315compresses the domain name 316.Fa exp_dn 317and stores it in 318.Fa comp_dn . 319The size of the compressed name is returned or \-1 if there were errors. 320The size of the array pointed to by 321.Fa comp_dn 322is given by 323.Fa length . 324The compression uses 325an array of pointers 326.Fa dnptrs 327to previously-compressed names in the current message. 328The first pointer points to 329the beginning of the message and the list ends with 330.Dv NULL . 331The limit to the array is specified by 332.Fa lastdnptr . 333A side effect of 334.Fn dn_comp 335is to update the list of pointers for 336labels inserted into the message 337as the name is compressed. 338If 339.Fa dnptr 340is 341.Dv NULL , 342names are not compressed. 343If 344.Fa lastdnptr 345is 346.Dv NULL , 347the list of labels is not updated. 348.Pp 349The 350.Fn dn_expand 351entry 352expands the compressed domain name 353.Fa comp_dn 354to a full domain name 355The compressed name is contained in a query or reply message; 356.Fa msg 357is a pointer to the beginning of the message. 358The uncompressed name is placed in the buffer indicated by 359.Fa exp_dn 360which is of size 361.Fa length . 362The size of compressed name is returned or \-1 if there was an error. 363.Pp 364The 365.Fn dn_skipname 366function skips over a compressed domain name, which starts at a location 367pointed to by 368.Fa comp_dn . 369The compressed name is contained in a query or reply message; 370.Fa eom 371is a pointer to the end of the message. 372The size of compressed name is returned or \-1 if there was 373an error. 374.Pp 375The 376.Fn ns_get16 377function gets a 16-bit quantity from a buffer pointed to by 378.Fa src . 379.Pp 380The 381.Fn ns_get32 382function gets a 32-bit quantity from a buffer pointed to by 383.Fa src . 384.Pp 385The 386.Fn ns_put16 387function puts a 16-bit quantity 388.Fa src 389to a buffer pointed to by 390.Fa dst . 391.Pp 392The 393.Fn ns_put32 394function puts a 32-bit quantity 395.Fa src 396to a buffer pointed to by 397.Fa dst . 398.Sh IMPLEMENTATION NOTES 399This implementation of the resolver is thread-safe, but it will not 400function properly if the programmer attempts to declare his or her own 401.Va _res 402structure in an attempt to replace the per-thread version referred to 403by that macro. 404.Sh RETURN VALUES 405The 406.Fn res_init 407function will return 0 on success, or \-1 in a threaded program if 408per-thread storage could not be allocated. 409.Pp 410The 411.Fn res_mkquery , 412.Fn res_search , 413and 414.Fn res_query 415functions return the size of the response on success, or \-1 if an 416error occurs. 417The integer 418.Vt h_errno 419may be checked to determine the reason for error. 420See 421.Xr gethostbyname 3 422for more information. 423.Sh FILES 424.Bl -tag -width /etc/resolv.conf 425.It Pa /etc/resolv.conf 426The configuration file, 427see 428.Xr resolver 5 . 429.El 430.Sh SEE ALSO 431.Xr gethostbyname 3 , 432.Xr resolver 5 , 433.Xr hostname 7 , 434.Xr named 8 435.Pp 436.%T RFC1032 , 437.%T RFC1033 , 438.%T RFC1034 , 439.%T RFC1035 , 440.%T RFC974 441.Rs 442.%T "Name Server Operations Guide for BIND" 443.Re 444.Sh HISTORY 445The 446.Nm 447function appeared in 448.Bx 4.3 . 449