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