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