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