lib/libc/net/resolver.3

   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 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)resolver.3  8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 29, 2009
  32 .Dt RESOLVER 3
  33 .Os
  34 .Sh NAME
  35 .Nm res_query ,
  36 .Nm res_search ,
  37 .Nm res_mkquery ,
  38 .Nm res_send ,
  39 .Nm res_init ,
  40 .Nm dn_comp ,
  41 .Nm dn_expand ,
  42 .Nm dn_skipname ,
  43 .Nm ns_get16 ,
  44 .Nm ns_get32 ,
  45 .Nm ns_put16 ,
  46 .Nm ns_put32
  47 .Nd resolver routines
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In sys/types.h
  52 .In netinet/in.h
  53 .In arpa/nameser.h
  54 .In resolv.h
  55 .Ft int
  56 .Fo res_query
  57 .Fa "const char *dname"
  58 .Fa "int class"
  59 .Fa "int type"
  60 .Fa "u_char *answer"
  61 .Fa "int anslen"
  62 .Fc
  63 .Ft int
  64 .Fo res_search
  65 .Fa "const char *dname"
  66 .Fa "int class"
  67 .Fa "int type"
  68 .Fa "u_char *answer"
  69 .Fa "int anslen"
  70 .Fc
  71 .Ft int
  72 .Fo res_mkquery
  73 .Fa "int op"
  74 .Fa "const char *dname"
  75 .Fa "int class"
  76 .Fa "int type"
  77 .Fa "const u_char *data"
  78 .Fa "int datalen"
  79 .Fa "const u_char *newrr_in"
  80 .Fa "u_char *buf"
  81 .Fa "int buflen"
  82 .Fc
  83 .Ft int
  84 .Fo res_send
  85 .Fa "const u_char *msg"
  86 .Fa "int msglen"
  87 .Fa "u_char *answer"
  88 .Fa "int anslen"
  89 .Fc
  90 .Ft int
  91 .Fn res_init void
  92 .Ft int
  93 .Fo dn_comp
  94 .Fa "const char *exp_dn"
  95 .Fa "u_char *comp_dn"
  96 .Fa "int length"
  97 .Fa "u_char **dnptrs"
  98 .Fa "u_char **lastdnptr"
  99 .Fc
 100 .Ft int
 101 .Fo dn_expand
 102 .Fa "const u_char *msg"
 103 .Fa "const u_char *eomorig"
 104 .Fa "const u_char *comp_dn"
 105 .Fa "char *exp_dn"
 106 .Fa "int length"
 107 .Fc
 108 .Ft int
 109 .Fn dn_skipname "const u_char *comp_dn" "const u_char *eom"
 110 .Ft u_int
 111 .Fn ns_get16 "const u_char *src"
 112 .Ft u_long
 113 .Fn ns_get32 "const u_char *src"
 114 .Ft void
 115 .Fn ns_put16 "u_int src" "u_char *dst"
 116 .Ft void
 117 .Fn ns_put32 "u_long src" "u_char *dst"
 118 .Sh DESCRIPTION
 119 These routines are used for making, sending and interpreting
 120 query and reply messages with Internet domain name servers.
 121 .Pp
 122 Global configuration and state information that is used by the
 123 resolver routines is kept in the structure
 124 .Va _res .
 125 Most of the values have reasonable defaults and can be ignored.
 126 Options
 127 stored in
 128 .Va _res.options
 129 are defined in
 130 .In resolv.h
 131 and are as follows.
 132 Options are stored as a simple bit mask containing the bitwise ``or''
 133 of the options enabled.
 134 .Bl -tag -width RES_USE_INET6
 135 .It Dv RES_INIT
 136 True if the initial name server address and default domain name are
 137 initialized (i.e.,
 138 .Fn res_init
 139 has been called).
 140 .It Dv RES_DEBUG
 141 Print debugging messages.
 142 .It Dv RES_AAONLY
 143 Accept authoritative answers only.
 144 With this option,
 145 .Fn res_send
 146 should continue until it finds an authoritative answer or finds an error.
 147 Currently this is not implemented.
 148 .It Dv RES_USEVC
 149 Use
 150 .Tn TCP
 151 connections for queries instead of
 152 .Tn UDP
 153 datagrams.
 154 .It Dv RES_STAYOPEN
 155 Used with
 156 .Dv RES_USEVC
 157 to keep the
 158 .Tn TCP
 159 connection open between
 160 queries.
 161 This is useful only in programs that regularly do many queries.
 162 .Tn UDP
 163 should be the normal mode used.
 164 .It Dv RES_IGNTC
 165 Unused currently (ignore truncation errors, i.e., do not retry with
 166 .Tn TCP ) .
 167 .It Dv RES_RECURSE
 168 Set the recursion-desired bit in queries.
 169 This is the default.
 170 .Pf ( Fn res_send
 171 does not do iterative queries and expects the name server
 172 to handle recursion.)
 173 .It Dv RES_DEFNAMES
 174 If set,
 175 .Fn res_search
 176 will append the default domain name to single-component names
 177 (those that do not contain a dot).
 178 This option is enabled by default.
 179 .It Dv RES_DNSRCH
 180 If this option is set,
 181 .Fn res_search
 182 will search for host names in the current domain and in parent domains; see
 183 .Xr hostname 7 .
 184 This is used by the standard host lookup routine
 185 .Xr gethostbyname 3 .
 186 This option is enabled by default.
 187 .It Dv RES_NOALIASES
 188 This option turns off the user level aliasing feature controlled by the
 189 .Dq Ev HOSTALIASES
 190 environment variable.
 191 Network daemons should set this option.
 192 .It Dv RES_USE_INET6
 193 Enables support for IPv6-only applications.
 194 This causes IPv4 addresses to be returned as an IPv4 mapped address.
 195 For example,
 196 .Li 10.1.1.1
 197 will be returned as
 198 .Li ::ffff:10.1.1.1 .
 199 The option is meaningful with certain kernel configuration only.
 200 .It Dv RES_USE_EDNS0
 201 Enables support for OPT pseudo-RR for EDNS0 extension.
 202 With the option, resolver code will attach OPT pseudo-RR into DNS queries,
 203 to inform of our receive buffer size.
 204 The option will allow DNS servers to take advantage of non-default receive
 205 buffer size, and to send larger replies.
 206 DNS query packets with EDNS0 extension is not compatible with
 207 non-EDNS0 DNS servers.
 208 .El
 209 .Pp
 210 The
 211 .Fn res_init
 212 routine
 213 reads the configuration file (if any; see
 214 .Xr resolver 5 )
 215 to get the default domain name,
 216 search list and
 217 the Internet address of the local name server(s).
 218 If no server is configured, the host running
 219 the resolver is tried.
 220 The current domain name is defined by the hostname
 221 if not specified in the configuration file;
 222 it can be overridden by the environment variable
 223 .Ev LOCALDOMAIN .
 224 This environment variable may contain several blank-separated
 225 tokens if you wish to override the
 226 .Em "search list"
 227 on a per-process basis.
 228 This is similar to the
 229 .Ic search
 230 command in the configuration file.
 231 Another environment variable
 232 .Dq Ev RES_OPTIONS
 233 can be set to
 234 override certain internal resolver options which are otherwise
 235 set by changing fields in the
 236 .Va _res
 237 structure or are inherited from the configuration file's
 238 .Ic options
 239 command.
 240 The syntax of the
 241 .Dq Ev RES_OPTIONS
 242 environment variable is explained in
 243 .Xr resolver 5 .
 244 Initialization normally occurs on the first call
 245 to one of the following routines.
 246 .Pp
 247 The
 248 .Fn res_query
 249 function provides an interface to the server query mechanism.
 250 It constructs a query, sends it to the local server,
 251 awaits a response, and makes preliminary checks on the reply.
 252 The query requests information of the specified
 253 .Fa type
 254 and
 255 .Fa class
 256 for the specified fully-qualified domain name
 257 .Fa dname .
 258 The reply message is left in the
 259 .Fa answer
 260 buffer with length
 261 .Fa anslen
 262 supplied by the caller.
 263 .Pp
 264 The
 265 .Fn res_search
 266 routine makes a query and awaits a response like
 267 .Fn res_query ,
 268 but in addition, it implements the default and search rules
 269 controlled by the
 270 .Dv RES_DEFNAMES
 271 and
 272 .Dv RES_DNSRCH
 273 options.
 274 It returns the first successful reply.
 275 .Pp
 276 The remaining routines are lower-level routines used by
 277 .Fn res_query .
 278 The
 279 .Fn res_mkquery
 280 function
 281 constructs a standard query message and places it in
 282 .Fa buf .
 283 It returns the size of the query, or \-1 if the query is
 284 larger than
 285 .Fa buflen .
 286 The query type
 287 .Fa op
 288 is usually
 289 .Dv QUERY ,
 290 but can be any of the query types defined in
 291 .In arpa/nameser.h .
 292 The domain name for the query is given by
 293 .Fa dname .
 294 The
 295 .Fa newrr_in
 296 argument
 297 is currently unused but is intended for making update messages.
 298 .Pp
 299 The
 300 .Fn res_send
 301 routine
 302 sends a pre-formatted query and returns an answer.
 303 It will call
 304 .Fn res_init
 305 if
 306 .Dv RES_INIT
 307 is not set, send the query to the local name server, and
 308 handle timeouts and retries.
 309 The length of the reply message is returned, or
 310 \-1 if there were errors.
 311 .Pp
 312 The
 313 .Fn dn_comp
 314 function
 315 compresses the domain name
 316 .Fa exp_dn
 317 and stores it in
 318 .Fa comp_dn .
 319 The size of the compressed name is returned or \-1 if there were errors.
 320 The size of the array pointed to by
 321 .Fa comp_dn
 322 is given by
 323 .Fa length .
 324 The compression uses
 325 an array of pointers
 326 .Fa dnptrs
 327 to previously-compressed names in the current message.
 328 The first pointer points to
 329 the beginning of the message and the list ends with
 330 .Dv NULL .
 331 The limit to the array is specified by
 332 .Fa lastdnptr .
 333 A side effect of
 334 .Fn dn_comp
 335 is to update the list of pointers for
 336 labels inserted into the message
 337 as the name is compressed.
 338 If
 339 .Fa dnptr
 340 is
 341 .Dv NULL ,
 342 names are not compressed.
 343 If
 344 .Fa lastdnptr
 345 is
 346 .Dv NULL ,
 347 the list of labels is not updated.
 348 .Pp
 349 The
 350 .Fn dn_expand
 351 entry
 352 expands the compressed domain name
 353 .Fa comp_dn
 354 to a full domain name
 355 The compressed name is contained in a query or reply message;
 356 .Fa msg
 357 is a pointer to the beginning of the message.
 358 The uncompressed name is placed in the buffer indicated by
 359 .Fa exp_dn
 360 which is of size
 361 .Fa length .
 362 The size of compressed name is returned or \-1 if there was an error.
 363 .Pp
 364 The
 365 .Fn dn_skipname
 366 function skips over a compressed domain name, which starts at a location
 367 pointed to by
 368 .Fa comp_dn .
 369 The compressed name is contained in a query or reply message;
 370 .Fa eom
 371 is a pointer to the end of the message.
 372 The size of compressed name is returned or \-1 if there was
 373 an error.
 374 .Pp
 375 The
 376 .Fn ns_get16
 377 function gets a 16-bit quantity from a buffer pointed to by
 378 .Fa src .
 379 .Pp
 380 The
 381 .Fn ns_get32
 382 function gets a 32-bit quantity from a buffer pointed to by
 383 .Fa src .
 384 .Pp
 385 The
 386 .Fn ns_put16
 387 function puts a 16-bit quantity
 388 .Fa src
 389 to a buffer pointed to by
 390 .Fa dst .
 391 .Pp
 392 The
 393 .Fn ns_put32
 394 function puts a 32-bit quantity
 395 .Fa src
 396 to a buffer pointed to by
 397 .Fa dst .
 398 .Sh IMPLEMENTATION NOTES
 399 This implementation of the resolver is thread-safe, but it will not
 400 function properly if the programmer attempts to declare his or her own
 401 .Va _res
 402 structure in an attempt to replace the per-thread version referred to
 403 by that macro.
 404 .Pp
 405 The following compile-time option can be specified to change the default
 406 behavior of resolver routines when necessary.
 407 .Bl -tag -width RES_ENFORCE_RFC1034
 408 .It Dv RES_ENFORCE_RFC1034
 409 If this symbol is defined during compile-time,
 410 .Fn res_search
 411 will enforce RFC 1034 check, namely, disallow using of underscore character
 412 within host names.
 413 This is used by the standard host lookup routines like
 414 .Xr gethostbyname 3 .
 415 For compatibility reasons this option is not enabled by default.
 416 .El
 417 .Sh RETURN VALUES
 418 The
 419 .Fn res_init
 420 function will return 0 on success, or \-1 in a threaded program if
 421 per-thread storage could not be allocated.
 422 .Pp
 423 The
 424 .Fn res_mkquery ,
 425 .Fn res_search ,
 426 and
 427 .Fn res_query
 428 functions return the size of the response on success, or \-1 if an
 429 error occurs.
 430 The integer
 431 .Vt h_errno
 432 may be checked to determine the reason for error.
 433 See
 434 .Xr gethostbyname 3
 435 for more information.
 436 .Sh FILES
 437 .Bl -tag -width /etc/resolv.conf
 438 .It Pa /etc/resolv.conf
 439 The configuration file,
 440 see
 441 .Xr resolver 5 .
 442 .El
 443 .Sh SEE ALSO
 444 .Xr gethostbyname 3 ,
 445 .Xr resolver 5 ,
 446 .Xr hostname 7 ,
 447 .Xr named 8
 448 .Pp
 449 .%T RFC1032 ,
 450 .%T RFC1033 ,
 451 .%T RFC1034 ,
 452 .%T RFC1035 ,
 453 .%T RFC974
 454 .Rs
 455 .%T "Name Server Operations Guide for BIND"
 456 .Re
 457 .Sh HISTORY
 458 The
 459 .Nm
 460 function appeared in
 461 .Bx 4.3 .