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: src/lib/libc/net/resolver.3,v 1.11.2.7 2001/12/14 18:33:55 ru Exp $ 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.Nd resolver routines 47.Sh LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.In sys/types.h 51.In netinet/in.h 52.In arpa/nameser.h 53.In resolv.h 54.Ft int 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.Ft int 63.Fo res_search 64.Fa "const char *dname" 65.Fa "int class" 66.Fa "int type" 67.Fa "u_char *answer" 68.Fa "int anslen" 69.Fc 70.Ft int 71.Fo res_mkquery 72.Fa "int op" 73.Fa "const char *dname" 74.Fa "int class" 75.Fa "int type" 76.Fa "const u_char *data" 77.Fa "int datalen" 78.Fa "const u_char *newrr_in" 79.Fa "u_char *buf" 80.Fa "int buflen" 81.Fc 82.Ft int 83.Fo res_send 84.Fa "const u_char *msg" 85.Fa "int msglen" 86.Fa "u_char *answer" 87.Fa "int anslen" 88.Fc 89.Ft int 90.Fn res_init 91.Fo dn_comp 92.Fa "const char *exp_dn" 93.Fa "u_char *comp_dn" 94.Fa "int length" 95.Fa "u_char **dnptrs" 96.Fa "u_char **lastdnptr" 97.Fc 98.Ft int 99.Fo dn_expand 100.Fa "const u_char *msg" 101.Fa "const u_char *eomorig" 102.Fa "const u_char *comp_dn" 103.Fa "char *exp_dn" 104.Fa "int length" 105.Fc 106.Sh DESCRIPTION 107These routines are used for making, sending and interpreting 108query and reply messages with Internet domain name servers. 109.Pp 110Global configuration and state information that is used by the 111resolver routines is kept in the structure 112.Em _res . 113Most of the values have reasonable defaults and can be ignored. 114Options 115stored in 116.Em _res.options 117are defined in 118.Pa resolv.h 119and are as follows. 120Options are stored as a simple bit mask containing the bitwise ``or'' 121of the options enabled. 122.Bl -tag -width RES_USE_INET6 123.It Dv RES_INIT 124True if the initial name server address and default domain name are 125initialized (i.e., 126.Fn res_init 127has been called). 128.It Dv RES_DEBUG 129Print debugging messages. 130.It Dv RES_AAONLY 131Accept authoritative answers only. 132With this option, 133.Fn res_send 134should continue until it finds an authoritative answer or finds an error. 135Currently this is not implemented. 136.It Dv RES_USEVC 137Use 138.Tn TCP 139connections for queries instead of 140.Tn UDP 141datagrams. 142.It Dv RES_STAYOPEN 143Used with 144.Dv RES_USEVC 145to keep the 146.Tn TCP 147connection open between 148queries. 149This is useful only in programs that regularly do many queries. 150.Tn UDP 151should be the normal mode used. 152.It Dv RES_IGNTC 153Unused currently (ignore truncation errors, i.e., don't retry with 154.Tn TCP ) . 155.It Dv RES_RECURSE 156Set the recursion-desired bit in queries. 157This is the default. 158.Pf ( Fn res_send 159does not do iterative queries and expects the name server 160to handle recursion.) 161.It Dv RES_DEFNAMES 162If set, 163.Fn res_search 164will append the default domain name to single-component names 165(those that do not contain a dot). 166This option is enabled by default. 167.It Dv RES_DNSRCH 168If this option is set, 169.Fn res_search 170will search for host names in the current domain and in parent domains; see 171.Xr hostname 7 . 172This is used by the standard host lookup routine 173.Xr gethostbyname 3 . 174This option is enabled by default. 175.It Dv RES_NOALIASES 176This option turns off the user level aliasing feature controlled by the 177.Dq Ev HOSTALIASES 178environment variable. Network daemons should set this option. 179.It Dv RES_USE_INET6 180Enables support for IPv6-only applications. 181This causes IPv4 addresses to be returned as an IPv4 mapped address. 182For example, 183.Li 10.1.1.1 184will be returned as 185.Li ::ffff:10.1.1.1 . 186The option is meaningful with certain kernel configuration only. 187.It Dv RES_USE_EDNS0 188Enables support for OPT pseudo-RR for EDNS0 extension. 189With the option, resolver code will attach OPT pseudo-RR into DNS queries, 190to inform of our receive buffer size. 191The option will allow DNS servers to take advantage of non-default receive 192buffer size, and to send larger replies. 193DNS query packets with EDNS0 extension is not compatible with 194non-EDNS0 DNS servers. 195.El 196.Pp 197The 198.Fn res_init 199routine 200reads the configuration file (if any; see 201.Xr resolver 5 ) 202to get the default domain name, 203search list and 204the Internet address of the local name server(s). 205If no server is configured, the host running 206the resolver is tried. 207The current domain name is defined by the hostname 208if not specified in the configuration file; 209it can be overridden by the environment variable 210.Ev LOCALDOMAIN . 211This environment variable may contain several blank-separated 212tokens if you wish to override the 213.Em "search list" 214on a per-process basis. This is similar to the 215.Em search 216command in the configuration file. 217Another environment variable 218.Dq Ev RES_OPTIONS 219can be set to 220override certain internal resolver options which are otherwise 221set by changing fields in the 222.Em _res 223structure or are inherited from the configuration file's 224.Em options 225command. The syntax of the 226.Dq Ev RES_OPTIONS 227environment variable is explained in 228.Xr resolver 5 . 229Initialization normally occurs on the first call 230to one of the following routines. 231.Pp 232The 233.Fn res_query 234function provides an interface to the server query mechanism. 235It constructs a query, sends it to the local server, 236awaits a response, and makes preliminary checks on the reply. 237The query requests information of the specified 238.Fa type 239and 240.Fa class 241for the specified fully-qualified domain name 242.Fa dname . 243The reply message is left in the 244.Fa answer 245buffer with length 246.Fa anslen 247supplied by the caller. 248.Pp 249The 250.Fn res_search 251routine makes a query and awaits a response like 252.Fn res_query , 253but in addition, it implements the default and search rules 254controlled by the 255.Dv RES_DEFNAMES 256and 257.Dv RES_DNSRCH 258options. 259It returns the first successful reply. 260.Pp 261The remaining routines are lower-level routines used by 262.Fn res_query . 263The 264.Fn res_mkquery 265function 266constructs a standard query message and places it in 267.Fa buf . 268It returns the size of the query, or \-1 if the query is 269larger than 270.Fa buflen . 271The query type 272.Fa op 273is usually 274.Dv QUERY , 275but can be any of the query types defined in 276.Aq Pa arpa/nameser.h . 277The domain name for the query is given by 278.Fa dname . 279.Fa Newrr 280is currently unused but is intended for making update messages. 281.Pp 282The 283.Fn res_send 284routine 285sends a pre-formatted query and returns an answer. 286It will call 287.Fn res_init 288if 289.Dv RES_INIT 290is not set, send the query to the local name server, and 291handle timeouts and retries. 292The length of the reply message is returned, or 293\-1 if there were errors. 294.Pp 295The 296.Fn dn_comp 297function 298compresses the domain name 299.Fa exp_dn 300and stores it in 301.Fa comp_dn . 302The size of the compressed name is returned or \-1 if there were errors. 303The size of the array pointed to by 304.Fa comp_dn 305is given by 306.Fa length . 307The compression uses 308an array of pointers 309.Fa dnptrs 310to previously-compressed names in the current message. 311The first pointer points to 312the beginning of the message and the list ends with 313.Dv NULL . 314The limit to the array is specified by 315.Fa lastdnptr . 316A side effect of 317.Fn dn_comp 318is to update the list of pointers for 319labels inserted into the message 320as the name is compressed. 321If 322.Em dnptr 323is 324.Dv NULL , 325names are not compressed. 326If 327.Fa lastdnptr 328is 329.Dv NULL , 330the list of labels is not updated. 331.Pp 332The 333.Fn dn_expand 334entry 335expands the compressed domain name 336.Fa comp_dn 337to a full domain name 338The compressed name is contained in a query or reply message; 339.Fa msg 340is a pointer to the beginning of the message. 341The uncompressed name is placed in the buffer indicated by 342.Fa exp_dn 343which is of size 344.Fa length . 345The size of compressed name is returned or \-1 if there was an error. 346.Sh FILES 347.Bl -tag -width /etc/resolv.conf 348.It Pa /etc/resolv.conf 349The configuration file, 350see 351.Xr resolver 5 . 352.El 353.Sh SEE ALSO 354.Xr gethostbyname 3 , 355.Xr resolver 5 , 356.Xr hostname 7 , 357.Xr named 8 358.Pp 359.%T RFC1032 , 360.%T RFC1033 , 361.%T RFC1034 , 362.%T RFC1035 , 363.%T RFC974 364.Rs 365.%T "Name Server Operations Guide for BIND" 366.Re 367.Sh HISTORY 368The 369.Nm 370function appeared in 371.Bx 4.3 . 372