1.\" Copyright (c) 1985, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)resolver.3 6.9 (Berkeley) 07/29/91 7.\" 8.Dd 9.Dt RESOLVER 3 10.Os BSD 4.3 11.Sh NAME 12.Nm res_query , 13.Nm res_search , 14.Nm res_mkquery , 15.Nm res_send , 16.Nm res_init , 17.Nm dn_comp , 18.Nm dn_expand 19.Nd resolver routines 20.Sh SYNOPSIS 21.Fd #include <sys/types.h> 22.Fd #include <netinet/in.h> 23.Fd #include <arpa/nameser.h> 24.Fd #include <resolv.h> 25.Fo res_query 26.Fa "char *dname" 27.Fa "int class" 28.Fa "int type" 29.Fa "u_char *answer" 30.Fa "int anslen" 31.Fc 32.Fo res_search 33.Fa "char *dname" 34.Fa "int class" 35.Fa "int type" 36.Fa "u_char *answer" 37.Fa "int anslen" 38.Fc 39.Fo res_mkquery 40.Fa "int op" 41.Fa "char *dname" 42.Fa "int class" 43.Fa "int type" 44.Fa "char *data" 45.Fa "int datalen" 46.Fa "struct rrec *newrr" 47.Fa "char *buf" 48.Fa "int buflen" 49.Fc 50.Fo res_send 51.Fa "char *msg" 52.Fa "int msglen" 53.Fa "char *answer" 54.Fa "int anslen" 55.Fc 56.Fn res_init 57.Fo dn_comp 58.Fa "char *exp_dn" 59.Fa "char *comp_dn" 60.Fa "int length" 61.Fa "char **dnptrs" 62.Fa "char **lastdnptr" 63.Fc 64.Fo dn_expand 65.Fa "u_char *msg" 66.Fa "u_char *eomorig" 67.Fa "u_char *comp_dn" 68.Fa "u_char *exp_dn" 69.Fa "int length" 70.Fc 71.Sh DESCRIPTION 72These routines are used for making, sending and interpreting 73query and reply messages with Internet domain name servers. 74.Pp 75Global configuration and state information that is used by the 76resolver routines is kept in the structure 77.Em _res . 78Most of the values have reasonable defaults and can be ignored. 79Options 80stored in 81.Em _res.options 82are defined in 83.Pa resolv.h 84and are as follows. 85Options are stored as a simple bit mask containing the bitwise ``or'' 86of the options enabled. 87.Bl -tag -width RES_DEFNAMES 88.It Dv RES_INIT 89True if the initial name server address and default domain name are 90initialized (i.e., 91.Fn res_init 92has been called). 93.It Dv RES_DEBUG 94Print debugging messages. 95.It Dv RES_AAONLY 96Accept authoritative answers only. 97With this option, 98.Fn res_send 99should continue until it finds an authoritative answer or finds an error. 100Currently this is not implemented. 101.It Dv RES_USEVC 102Use 103.Tn TCP 104connections for queries instead of 105.Tn UDP 106datagrams. 107.It Dv RES_STAYOPEN 108Used with 109.Dv RES_USEVC 110to keep the 111.Tn TCP 112connection open between 113queries. 114This is useful only in programs that regularly do many queries. 115.Tn UDP 116should be the normal mode used. 117.It Dv RES_IGNTC 118Unused currently (ignore truncation errors, i.e., don't retry with 119.Tn TCP ) . 120.It Dv RES_RECURSE 121Set the recursion-desired bit in queries. 122This is the default. 123.Pf ( Fn res_send 124does not do iterative queries and expects the name server 125to handle recursion.) 126.It Dv RES_DEFNAMES 127If set, 128.Fn res_search 129will append the default domain name to single-component names 130(those that do not contain a dot). 131This option is enabled by default. 132.It Dv RES_DNSRCH 133If this option is set, 134.Fn res_search 135will search for host names in the current domain and in parent domains; see 136.Xr hostname 7 . 137This is used by the standard host lookup routine 138.Xr gethostbyname 3 . 139This option is enabled by default. 140.El 141.Pp 142The 143.Fn res_init 144routine 145reads the configuration file (if any; see 146.Xr resolver 5 ) 147to get the default domain name, 148search list and 149the Internet address of the local name server(s). 150If no server is configured, the host running 151the resolver is tried. 152The current domain name is defined by the hostname 153if not specified in the configuration file; 154it can be overridden by the environment variable 155.Ev LOCALDOMAIN . 156Initialization normally occurs on the first call 157to one of the following routines. 158.Pp 159The 160.Fn res_query 161function provides an interface to the server query mechanism. 162It constructs a query, sends it to the local server, 163awaits a response, and makes preliminary checks on the reply. 164The query requests information of the specified 165.Fa type 166and 167.Fa class 168for the specified fully-qualified domain name 169.Fa dname . 170The reply message is left in the 171.Fa answer 172buffer with length 173.Fa anslen 174supplied by the caller. 175.Pp 176The 177.Fn res_search 178routine makes a query and awaits a response like 179.Fn res_query , 180but in addition, it implements the default and search rules 181controlled by the 182.Dv RES_DEFNAMES 183and 184.Dv RES_DNSRCH 185options. 186It returns the first successful reply. 187.Pp 188The remaining routines are lower-level routines used by 189.Fn res_query . 190The 191.Fn res_mkquery 192function 193constructs a standard query message and places it in 194.Fa buf . 195It returns the size of the query, or \-1 if the query is 196larger than 197.Fa buflen . 198The query type 199.Fa op 200is usually 201.Dv QUERY , 202but can be any of the query types defined in 203.Aq Pa arpa/nameser.h . 204The domain name for the query is given by 205.Fa dname . 206.Fa Newrr 207is currently unused but is intended for making update messages. 208.Pp 209The 210.Fn res_send 211routine 212sends a pre-formatted query and returns an answer. 213It will call 214.Fn res_init 215if 216.Dv RES_INIT 217is not set, send the query to the local name server, and 218handle timeouts and retries. 219The length of the reply message is returned, or 220\-1 if there were errors. 221.Pp 222The 223.Fn dn_comp 224function 225compresses the domain name 226.Fa exp_dn 227and stores it in 228.Fa comp_dn . 229The size of the compressed name is returned or \-1 if there were errors. 230The size of the array pointed to by 231.Fa comp_dn 232is given by 233.Fa length . 234The compression uses 235an array of pointers 236.Fa dnptrs 237to previously-compressed names in the current message. 238The first pointer points to 239to the beginning of the message and the list ends with 240.Dv NULL . 241The limit to the array is specified by 242.Fa lastdnptr . 243A side effect of 244.Fn dn_comp 245is to update the list of pointers for 246labels inserted into the message 247as the name is compressed. 248If 249.Em dnptr 250is 251.Dv NULL, names are not compressed. 252If 253.Fa lastdnptr 254is 255.Dv NULL , 256the list of labels is not updated. 257.Pp 258The 259.Fn dn_expand 260entry 261expands the compressed domain name 262.Fa comp_dn 263to a full domain name 264The compressed name is contained in a query or reply message; 265.Fa msg 266is a pointer to the beginning of the message. 267The uncompressed name is placed in the buffer indicated by 268.Fa exp_dn 269which is of size 270.Fa length . 271The size of compressed name is returned or \-1 if there was an error. 272.Sh FILES 273.Bl -tag -width Pa 274/etc/resolv.conf 275The configuration file 276see 277.Xr resolver 5 . 278.El 279.Sh SEE ALSO 280.Xr gethostbyname 3 , 281.Xr named 8 , 282.Xr resolver 5 , 283.Xr hostname 7 , 284.Pp 285.%T RFC1032 , 286.%T RFC1033 , 287.%T RFC1034 , 288.%T RFC1035 , 289.%T RFC974 290.Rs 291.%T "Name Server Operations Guide for BIND" 292.Re 293.Sh HISTORY 294The 295.Nm 296function appeared in 297.Bx 4.3 . 298