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$ 34.\" 35.Dd June 4, 1993 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 LIBRARY 48.Lb libc 49.Sh SYNOPSIS 50.Fd #include <sys/types.h> 51.Fd #include <netinet/in.h> 52.Fd #include <arpa/nameser.h> 53.Fd #include <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_DEFNAMES 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.El 180.Pp 181The 182.Fn res_init 183routine 184reads the configuration file (if any; see 185.Xr resolver 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.Em "search list" 198on a per-process basis. This is similar to the 199.Em search 200command in the configuration file. 201Another environment variable ( 202.Dq Ev RES_OPTIONS 203can be set to 204override certain internal resolver options which are otherwise 205set by changing fields in the 206.Em _res 207structure or are inherited from the configuration file's 208.Em options 209command. The syntax of the 210.Dq Ev RES_OPTIONS 211environment variable is explained in 212.Xr resolver 5 . 213Initialization normally occurs on the first call 214to one of the following routines. 215.Pp 216The 217.Fn res_query 218function provides an interface to the server query mechanism. 219It constructs a query, sends it to the local server, 220awaits a response, and makes preliminary checks on the reply. 221The query requests information of the specified 222.Fa type 223and 224.Fa class 225for the specified fully-qualified domain name 226.Fa dname . 227The reply message is left in the 228.Fa answer 229buffer with length 230.Fa anslen 231supplied by the caller. 232.Pp 233The 234.Fn res_search 235routine makes a query and awaits a response like 236.Fn res_query , 237but in addition, it implements the default and search rules 238controlled by the 239.Dv RES_DEFNAMES 240and 241.Dv RES_DNSRCH 242options. 243It returns the first successful reply. 244.Pp 245The remaining routines are lower-level routines used by 246.Fn res_query . 247The 248.Fn res_mkquery 249function 250constructs a standard query message and places it in 251.Fa buf . 252It returns the size of the query, or \-1 if the query is 253larger than 254.Fa buflen . 255The query type 256.Fa op 257is usually 258.Dv QUERY , 259but can be any of the query types defined in 260.Aq Pa arpa/nameser.h . 261The domain name for the query is given by 262.Fa dname . 263.Fa Newrr 264is currently unused but is intended for making update messages. 265.Pp 266The 267.Fn res_send 268routine 269sends a pre-formatted query and returns an answer. 270It will call 271.Fn res_init 272if 273.Dv RES_INIT 274is not set, send the query to the local name server, and 275handle timeouts and retries. 276The length of the reply message is returned, or 277\-1 if there were errors. 278.Pp 279The 280.Fn dn_comp 281function 282compresses the domain name 283.Fa exp_dn 284and stores it in 285.Fa comp_dn . 286The size of the compressed name is returned or \-1 if there were errors. 287The size of the array pointed to by 288.Fa comp_dn 289is given by 290.Fa length . 291The compression uses 292an array of pointers 293.Fa dnptrs 294to previously-compressed names in the current message. 295The first pointer points to 296the beginning of the message and the list ends with 297.Dv NULL . 298The limit to the array is specified by 299.Fa lastdnptr . 300A side effect of 301.Fn dn_comp 302is to update the list of pointers for 303labels inserted into the message 304as the name is compressed. 305If 306.Em dnptr 307is 308.Dv NULL, names are not compressed. 309If 310.Fa lastdnptr 311is 312.Dv NULL , 313the list of labels is not updated. 314.Pp 315The 316.Fn dn_expand 317entry 318expands the compressed domain name 319.Fa comp_dn 320to a full domain name 321The compressed name is contained in a query or reply message; 322.Fa msg 323is a pointer to the beginning of the message. 324The uncompressed name is placed in the buffer indicated by 325.Fa exp_dn 326which is of size 327.Fa length . 328The size of compressed name is returned or \-1 if there was an error. 329.Sh FILES 330.Bl -tag -width /etc/resolv.conf 331.It Pa /etc/resolv.conf 332The configuration file, 333see 334.Xr resolver 5 . 335.El 336.Sh SEE ALSO 337.Xr gethostbyname 3 , 338.Xr resolver 5 , 339.Xr hostname 7 , 340.Xr named 8 341.Pp 342.%T RFC1032 , 343.%T RFC1033 , 344.%T RFC1034 , 345.%T RFC1035 , 346.%T RFC974 347.Rs 348.%T "Name Server Operations Guide for BIND" 349.Re 350.Sh HISTORY 351The 352.Nm 353function appeared in 354.Bx 4.3 . 355