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.\" @(#)resolver.3 6.9 (Berkeley) 7/29/91 33.\" 34.Dd July 29, 1991 35.Dt RESOLVER 3 36.Os BSD 4.3 37.Sh NAME 38.Nm res_query , 39.Nm res_search , 40.Nm res_mkquery , 41.Nm res_send , 42.Nm res_init , 43.Nm dn_comp , 44.Nm dn_expand 45.Nd resolver routines 46.Sh SYNOPSIS 47.Fd #include <sys/types.h> 48.Fd #include <netinet/in.h> 49.Fd #include <arpa/nameser.h> 50.Fd #include <resolv.h> 51.Fo res_query 52.Fa "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 "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 "char *dname" 68.Fa "int class" 69.Fa "int type" 70.Fa "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 "char *msg" 78.Fa "int msglen" 79.Fa "char *answer" 80.Fa "int anslen" 81.Fc 82.Fn res_init 83.Fo dn_comp 84.Fa "char *exp_dn" 85.Fa "char *comp_dn" 86.Fa "int length" 87.Fa "char **dnptrs" 88.Fa "char **lastdnptr" 89.Fc 90.Fo dn_expand 91.Fa "u_char *msg" 92.Fa "u_char *eomorig" 93.Fa "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_DEFNAMES 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.El 167.Pp 168The 169.Fn res_init 170routine 171reads the configuration file (if any; see 172.Xr resolver 5 ) 173to get the default domain name, 174search list and 175the Internet address of the local name server(s). 176If no server is configured, the host running 177the resolver is tried. 178The current domain name is defined by the hostname 179if not specified in the configuration file; 180it can be overridden by the environment variable 181.Ev LOCALDOMAIN . 182Initialization normally occurs on the first call 183to one of the following routines. 184.Pp 185The 186.Fn res_query 187function provides an interface to the server query mechanism. 188It constructs a query, sends it to the local server, 189awaits a response, and makes preliminary checks on the reply. 190The query requests information of the specified 191.Fa type 192and 193.Fa class 194for the specified fully-qualified domain name 195.Fa dname . 196The reply message is left in the 197.Fa answer 198buffer with length 199.Fa anslen 200supplied by the caller. 201.Pp 202The 203.Fn res_search 204routine makes a query and awaits a response like 205.Fn res_query , 206but in addition, it implements the default and search rules 207controlled by the 208.Dv RES_DEFNAMES 209and 210.Dv RES_DNSRCH 211options. 212It returns the first successful reply. 213.Pp 214The remaining routines are lower-level routines used by 215.Fn res_query . 216The 217.Fn res_mkquery 218function 219constructs a standard query message and places it in 220.Fa buf . 221It returns the size of the query, or \-1 if the query is 222larger than 223.Fa buflen . 224The query type 225.Fa op 226is usually 227.Dv QUERY , 228but can be any of the query types defined in 229.Aq Pa arpa/nameser.h . 230The domain name for the query is given by 231.Fa dname . 232.Fa Newrr 233is currently unused but is intended for making update messages. 234.Pp 235The 236.Fn res_send 237routine 238sends a pre-formatted query and returns an answer. 239It will call 240.Fn res_init 241if 242.Dv RES_INIT 243is not set, send the query to the local name server, and 244handle timeouts and retries. 245The length of the reply message is returned, or 246\-1 if there were errors. 247.Pp 248The 249.Fn dn_comp 250function 251compresses the domain name 252.Fa exp_dn 253and stores it in 254.Fa comp_dn . 255The size of the compressed name is returned or \-1 if there were errors. 256The size of the array pointed to by 257.Fa comp_dn 258is given by 259.Fa length . 260The compression uses 261an array of pointers 262.Fa dnptrs 263to previously-compressed names in the current message. 264The first pointer points to 265to the beginning of the message and the list ends with 266.Dv NULL . 267The limit to the array is specified by 268.Fa lastdnptr . 269A side effect of 270.Fn dn_comp 271is to update the list of pointers for 272labels inserted into the message 273as the name is compressed. 274If 275.Em dnptr 276is 277.Dv NULL, names are not compressed. 278If 279.Fa lastdnptr 280is 281.Dv NULL , 282the list of labels is not updated. 283.Pp 284The 285.Fn dn_expand 286entry 287expands the compressed domain name 288.Fa comp_dn 289to a full domain name 290The compressed name is contained in a query or reply message; 291.Fa msg 292is a pointer to the beginning of the message. 293The uncompressed name is placed in the buffer indicated by 294.Fa exp_dn 295which is of size 296.Fa length . 297The size of compressed name is returned or \-1 if there was an error. 298.Sh FILES 299.Bl -tag -width Pa 300/etc/resolv.conf 301The configuration file 302see 303.Xr resolver 5 . 304.El 305.Sh SEE ALSO 306.Xr gethostbyname 3 , 307.Xr named 8 , 308.Xr resolver 5 , 309.Xr hostname 7 , 310.Pp 311.%T RFC1032 , 312.%T RFC1033 , 313.%T RFC1034 , 314.%T RFC1035 , 315.%T RFC974 316.Rs 317.%T "Name Server Operations Guide for BIND" 318.Re 319.Sh HISTORY 320The 321.Nm 322function appeared in 323.Bx 4.3 . 324