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