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