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