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