contrib/bind/man/resolver.3

   1 .\" Copyright (c) 1985, 1995 The Regents of the University of California.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms are permitted provided
   5 .\" that: (1) source distributions retain this entire copyright notice and
   6 .\" comment, and (2) distributions including binaries display the following
   7 .\" acknowledgement:  ``This product includes software developed by the
   8 .\" University of California, Berkeley and its contributors'' in the
   9 .\" documentation or other materials provided with the distribution and in
  10 .\" all advertising materials mentioning features or use of this software.
  11 .\" Neither the name of the University nor the names of its contributors may
  12 .\" be used to endorse or promote products derived from this software without
  13 .\" specific prior written permission.
  14 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  15 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  16 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  17 .\"
  18 .\"     @(#)resolver.3  6.5 (Berkeley) 6/23/90
  19 .\"     $Id: resolver.3,v 8.4 1996/05/09 05:59:10 vixie Exp $
  20 .\"
  21 .TH RESOLVER @LIB_NETWORK_EXT_U@ "December 11, 1995
  22 .UC 4
  23 .SH NAME
  24 res_query, res_search, res_mkquery, res_send, res_init, dn_comp, dn_expand \- resolver routines
  25 .SH SYNOPSIS
  26 .B #include <sys/types.h>
  27 .br
  28 .B #include <netinet/in.h>
  29 .br
  30 .B #include <arpa/nameser.h>
  31 .br
  32 .B #include <resolv.h>
  33 .PP
  34 .B "res_query(dname, class, type, answer, anslen)"
  35 .br
  36 .B const char *dname;
  37 .br
  38 .B int class, type;
  39 .br
  40 .B u_char *answer;
  41 .br
  42 .B int anslen;
  43 .PP
  44 .B "res_search(dname, class, type, answer, anslen)"
  45 .br
  46 .B const char *dname;
  47 .br
  48 .B int class, type;
  49 .br
  50 .B u_char *answer;
  51 .br
  52 .B int anslen;
  53 .PP
  54 .B "res_mkquery(op, dname, class, type, data, datalen, newrr, buf, buflen)"
  55 .br
  56 .B int op;
  57 .br
  58 .B const char *dname;
  59 .br
  60 .B int class, type;
  61 .br
  62 .B const char *data;
  63 .br
  64 .B int datalen;
  65 .br
  66 .B struct rrec *newrr;
  67 .br
  68 .B u_char *buf;
  69 .br
  70 .B int buflen;
  71 .PP
  72 .B res_send(msg, msglen, answer, anslen)
  73 .br
  74 .B const u_char *msg;
  75 .br
  76 .B int msglen;
  77 .br
  78 .B u_char *answer;
  79 .br
  80 .B int anslen;
  81 .PP
  82 .B res_init()
  83 .PP
  84 .B dn_comp(exp_dn, comp_dn, length, dnptrs, lastdnptr)
  85 .br
  86 .B const char *exp_dn;
  87 .br
  88 .B u_char *comp_dn;
  89 .br
  90 .B int length;
  91 .br
  92 .B u_char **dnptrs, **lastdnptr;
  93 .PP
  94 .B dn_expand(msg, eomorig, comp_dn, exp_dn, length)
  95 .br
  96 .B const u_char *msg, *eomorig, *comp_dn;
  97 .br
  98 .B char *exp_dn;
  99 .br
 100 .B int  length;
 101 .PP
 102 .B herror(const char *s)
 103 .PP
 104 .B hstrerror(int err)
 105 .SH DESCRIPTION
 106 These routines are used for making, sending and interpreting
 107 query and reply messages with Internet domain name servers.
 108 .PP
 109 Global configuration and state information that is used by the
 110 resolver routines is kept in the structure
 111 .IR _res .
 112 Most of the values have reasonable defaults and can be ignored.
 113 Options
 114 stored in
 115 .I _res.options
 116 are defined in
 117 .I resolv.h
 118 and are as follows.
 119 Options are stored as a simple bit mask containing the bitwise ``or''
 120 of the options enabled.
 121 .IP RES_INIT
 122 True if the initial name server address and default domain name are
 123 initialized (i.e.,
 124 .I res_init
 125 has been called).
 126 .IP RES_DEBUG
 127 Print debugging messages.
 128 .IP RES_AAONLY
 129 Accept authoritative answers only.
 130 With this option,
 131 .I res_send
 132 should continue until it finds an authoritative answer or finds an error.
 133 Currently this is not implemented.
 134 .IP RES_USEVC
 135 Use TCP connections for queries instead of UDP datagrams.
 136 .IP RES_STAYOPEN
 137 Used with RES_USEVC to keep the TCP connection open between
 138 queries.
 139 This is useful only in programs that regularly do many queries.
 140 UDP should be the normal mode used.
 141 .IP RES_IGNTC
 142 Unused currently (ignore truncation errors, i.e., don't retry with TCP).
 143 .IP RES_RECURSE
 144 Set the recursion-desired bit in queries.
 145 This is the default.
 146 (\c
 147 .I res_send
 148 does not do iterative queries and expects the name server
 149 to handle recursion.)
 150 .IP RES_DEFNAMES
 151 If set,
 152 .I res_search
 153 will append the default domain name to single-component names
 154 (those that do not contain a dot).
 155 This option is enabled by default.
 156 .IP RES_DNSRCH
 157 If this option is set,
 158 .I res_search
 159 will search for host names in the current domain and in parent domains; see
 160 .IR hostname (@DESC_EXT@).
 161 This is used by the standard host lookup routine
 162 .IR gethostbyname (@LIB_NETWORK_EXT@).
 163 This option is enabled by default.
 164 .IP RES_NOALIASES
 165 This option turns off the user level aliasing feature controlled by
 166 the HOSTALIASES environment variable.  Network daemons should set this option.
 167 .PP
 168 The
 169 .I res_init
 170 routine
 171 reads the configuration file (if any; see
 172 .IR resolver (@FORMAT_EXT@))
 173 to get the default domain name,
 174 search list and
 175 the Internet address of the local name server(s).
 176 If no server is configured, the host running
 177 the resolver is tried.
 178 The current domain name is defined by the hostname
 179 if not specified in the configuration file;
 180 it can be overridden by the environment variable LOCALDOMAIN.
 181 This environment variable may contain several blank-separated
 182 tokens if you wish to override the
 183 .I "search list"
 184 on a per-process basis.  This is similar to the
 185 .I search
 186 command in the configuration file.
 187 Another environment variable (``RES_OPTIONS'') can be set to
 188 override certain internal resolver options which are otherwise
 189 set by changing fields in the
 190 .I _res
 191 structure or are inherited from the configuration file's
 192 .I options
 193 command.  The syntax of the ``RES_OPTIONS'' environment variable
 194 is explained in
 195 .IR resolver (@FORMAT_EXT@).
 196 Initialization normally occurs on the first call
 197 to one of the other resolver routines.
 198 .PP
 199 The
 200 .I res_query
 201 function provides an interface to the server query mechanism.
 202 It constructs a query, sends it to the local server,
 203 awaits a response, and makes preliminary checks on the reply.
 204 The query requests information of the specified
 205 .I type
 206 and
 207 .I class
 208 for the specified fully-qualified domain name
 209 .I dname .
 210 The reply message is left in the
 211 .I answer
 212 buffer with length
 213 .I anslen
 214 supplied by the caller.
 215 .PP
 216 The
 217 .I res_search
 218 routine makes a query and awaits a response like
 219 .IR res_query ,
 220 but in addition, it implements the default and search rules
 221 controlled by the RES_DEFNAMES and RES_DNSRCH options.
 222 It returns the first successful reply.
 223 .PP
 224 The remaining routines are lower-level routines used by
 225 .IR res_query .
 226 The
 227 .I res_mkquery
 228 function
 229 constructs a standard query message and places it in
 230 .IR buf .
 231 It returns the size of the query, or \-1 if the query is
 232 larger than
 233 .IR buflen .
 234 The query type
 235 .I op
 236 is usually QUERY, but can be any of the query types defined in
 237 .IR <arpa/nameser.h> .
 238 The domain name for the query is given by
 239 .IR dname .
 240 .I Newrr
 241 is currently unused but is intended for making update messages.
 242 .PP
 243 The
 244 .I res_send
 245 routine
 246 sends a pre-formatted query and returns an answer.
 247 It will call
 248 .I res_init
 249 if RES_INIT is not set, send the query to the local name server, and
 250 handle timeouts and retries.
 251 The length of the reply message is returned, or
 252 \-1 if there were errors.
 253 .PP
 254 The
 255 .I dn_comp
 256 function
 257 compresses the domain name
 258 .I exp_dn
 259 and stores it in
 260 .IR comp_dn .
 261 The size of the compressed name is returned or \-1 if there were errors.
 262 The size of the array pointed to by
 263 .I comp_dn
 264 is given by
 265 .IR length .
 266 The compression uses
 267 an array of pointers
 268 .I dnptrs
 269 to previously-compressed names in the current message.
 270 The first pointer points to
 271 to the beginning of the message and the list ends with NULL.
 272 The limit to the array is specified by
 273 .IR lastdnptr .
 274 A side effect of
 275 .I dn_comp
 276 is to update the list of pointers for
 277 labels inserted into the message
 278 as the name is compressed.
 279 If
 280 .I dnptr
 281 is NULL, names are not compressed.
 282 If
 283 .I lastdnptr
 284 is NULL, the list of labels is not updated.
 285 .PP
 286 The
 287 .I dn_expand
 288 entry
 289 expands the compressed domain name
 290 .I comp_dn
 291 to a full domain name
 292 The compressed name is contained in a query or reply message;
 293 .I msg
 294 is a pointer to the beginning of the message.
 295 The uncompressed name is placed in the buffer indicated by
 296 .I exp_dn
 297 which is of size
 298 .IR length .
 299 The size of compressed name is returned or \-1 if there was an error.
 300 .PP
 301 The external variable
 302 .B h_errno
 303 is set whenever an error occurs during resolver operation.  The following
 304 definitions are given in
 305 .BR <netdb.h> :
 306 .PP
 307 .nf
 308 #define NETDB_INTERNAL -1  /* see errno */
 309 #define NETDB_SUCCESS  0   /* no problem */
 310 #define HOST_NOT_FOUND 1   /* Authoritative Answer Host not found */
 311 #define TRY_AGAIN      2   /* Non-Authoritive not found, or SERVFAIL */
 312 #define NO_RECOVERY    3   /* Nonrecoverable: FORMERR, REFUSED, NOTIMP */
 313 #define NO_DATA        4   /* Valid name, no data for requested type */
 314 .ft R
 315 .ad
 316 .fi
 317 .PP
 318 The
 319 .B herror
 320 function writes a message to the diagnostic output consisting of the string
 321 parameter
 322 .BR s ,
 323 the constant string ": ", and a message corresponding to the value of
 324 .BR h_errno .
 325 .PP
 326 The
 327 .B hstrerror
 328 function returns a string which is the message text corresponding to the
 329 value of the
 330 .B err
 331 parameter.
 332 .SH FILES
 333 /etc/resolv.conf        see resolver(@FORMAT_EXT@)
 334 .SH "SEE ALSO"
 335 gethostbyname(@LIB_NETWORK_EXT@), @INDOT@named(@SYS_OPS_EXT@), resolver(@FORMAT_EXT@), hostname(@DESC_EXT@),
 336 .br
 337 RFC1032, RFC1033, RFC1034, RFC1035, RFC974,
 338 .br
 339 SMM:11 Name Server Operations Guide for BIND