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