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.In sys/types.h 56.In netinet/in.h 57.In arpa/nameser.h 58.In 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.Va _res . 129Most of the values have reasonable defaults and can be ignored. 130Options 131stored in 132.Va _res.options 133are defined in 134.In 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.Ic 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.Va _res 239structure or are inherited from the configuration file's 240.Ic 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.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 FILES 400.Bl -tag -width /etc/resolv.conf 401.It Pa /etc/resolv.conf 402The configuration file, 403see 404.Xr resolver 5 . 405.El 406.Sh SEE ALSO 407.Xr gethostbyname 3 , 408.Xr resolver 5 , 409.Xr hostname 7 , 410.Xr named 8 411.Pp 412.%T RFC1032 , 413.%T RFC1033 , 414.%T RFC1034 , 415.%T RFC1035 , 416.%T RFC974 417.Rs 418.%T "Name Server Operations Guide for BIND" 419.Re 420.Sh HISTORY 421The 422.Nm 423function appeared in 424.Bx 4.3 . 425