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