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