manual/bind/original/man3/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.13 2000/12/05 02:37:33 vixie Exp $
  20 .\"
  21 .Dd July 4, 2000
  22 .Dt RESOLVER 3
  23 .Os BSD 4
  24 .Sh NAME
  25 .Nm res_ninit ,
  26 .Nm res_ourserver_p ,
  27 .Nm fp_resstat ,
  28 .Nm res_hostalias ,
  29 .Nm res_pquery ,
  30 .Nm res_nquery ,
  31 .Nm res_nsearch ,
  32 .Nm res_nquerydomain ,
  33 .Nm res_nmkquery ,
  34 .Nm res_nsend ,
  35 .Nm res_nupdate ,
  36 .Nm res_nmkupdate ,
  37 .Nm res_nclose ,
  38 .Nm res_nsendsigned ,
  39 .Nm res_findzonecut ,
  40 .Nm dn_comp ,
  41 .Nm dn_expand ,
  42 .Nm hstrerror ,
  43 .Nm res_init ,
  44 .Nm res_isourserver ,
  45 .Nm fp_nquery ,
  46 .Nm p_query ,
  47 .Nm hostalias ,
  48 .Nm res_query ,
  49 .Nm res_search ,
  50 .Nm res_querydomain ,
  51 .Nm res_mkquery ,
  52 .Nm res_send ,
  53 .Nm res_update ,
  54 .Nm res_close ,
  55 .Nm herror
  56 .Nd resolver routines
  57 .Sh SYNOPSIS
  58 .Fd #include <sys/types.h>
  59 .Fd #include <netinet/in.h>
  60 .Fd #include <arpa/nameser.h>
  61 .Fd #include <resolv.h>
  62 .Ft typedef struct __res_state *res_state;
  63 .Pp
  64 .Fn res_ninit "res_state statp"
  65 .Fn res_ourserver_p "const res_state statp" "const struct sockaddr_in *addr"
  66 .Fn fp_resstat "const res_state statp" "FILE *fp"
  67 .Fn res_hostalias "const res_state statp" "const char *name" "char *buf" "size_t buflen"
  68 .Fn res_pquery "const res_state statp" "const u_char *msg" "int msglen" "FILE *fp"
  69 .Fn res_nquery "res_state statp" "const char *dname" "int class" "int type" "u_char *answer" "int anslen"
  70 .Fn res_nsearch "res_state statp" "const char *dname" "int class" "int type" "u_char * answer" "int anslen"
  71 .Fn res_nquerydomain "res_state statp" "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen"
  72 .Fn res_nmkquery "res_state statp, int op, const char *dname" "int class" "int type" "const u_char *data" "int datalen" "const u_char *newrr" "u_char *buf" "int buflen"
  73 .Fn res_nsend "res_state statp" "const u_char *msg" "int msglen" "u_char *answer" "int anslen"
  74 .Fn res_nupdate "res_state statp" "ns_updrec *rrecp_in"
  75 .Fn res_nmkupdate "res_state statp" "ns_updrec *rrecp_in" "u_char *buf" "int buflen"
  76 .Fn res_nclose "res_state statp"
  77 .Fn res_nsendsigned "res_state statp" "const u_char *msg" "int msglen" "ns_tsig_key *key" "u_char *answer" "int anslen"
  78 .Fn res_findzonecut "res_state statp" "const char *dname" "ns_class class" "int options" "char *zname" "size_t zsize" "struct in_addr *addrs" "int naddrs"
  79 .Fn dn_comp "const char *exp_dn" "u_char *comp_dn" "int length" "u_char **dnptrs, **lastdnptr"
  80 .Fn dn_expand "const u_char *msg, *eomorig, *comp_dn" "char *exp_dn" "int  length"
  81 .Fn hstrerror "int err"
  82 .Sh DEPRECATED
  83 .nr nS 1
  84 .Fd #include <sys/types.h>
  85 .Fd #include <netinet/in.h>
  86 .Fd #include <arpa/nameser.h>
  87 .Fd #include <resolv.h>
  88 .Fn res_init "void"
  89 .Fn res_isourserver "const struct sockaddr_in *addr"
  90 .Fn fp_nquery "const u_char *msg" "int msglen" "FILE *fp"
  91 .Fn p_query "const u_char *msg" "FILE *fp"
  92 .Fn hostalias "const char *name"
  93 .Fn res_query "const char *dname" "int class, type" "u_char *answer" "int anslen"
  94 .Fn res_search "const char *dname" "int class, type" "u_char *answer" "int anslen"
  95 .Fn res_querydomain "const char *name" "const char *domain" "int class" "int type" "u_char *answer" "int anslen"
  96 .Fn res_mkquery "int op" "const char *dname, int class, type" "const char *data" "int datalen" "struct rrec *newrr" "u_char *buf" "int buflen"
  97 .Fn res_send "const u_char *msg" "int msglen" "u_char *answer" "int anslen"
  98 .Fn res_update "ns_updrec *rrecp_in"
  99 .Fn res_close "void"
 100 .Fn herror "const char *s"
 101 .Sh DESCRIPTION
 102 These routines are used for making, sending and interpreting
 103 query and reply messages with Internet domain name servers.
 104 .Pp
 105 State information is kept in
 106 .Fa statp
 107 and is used to control the behavior of these functions.
 108 .Fa statp
 109 should be set to all zeros prior to the first call to any of these functions.
 110 .Pp
 111 The functions
 112 .Fn res_init ,
 113 .Fn res_isourserver ,
 114 .Fn fp_nquery ,
 115 .Fn p_query ,
 116 .Fn hostalias ,
 117 .Fn res_query ,
 118 .Fn res_search ,
 119 .Fn res_querydomain ,
 120 .Fn res_mkquery ,
 121 .Fn res_send ,
 122 .Fn res_update ,
 123 .Fn res_close
 124 and
 125 .Fn herror
 126 are deprecated and are supplied for compatability with old source
 127 code.
 128 They use global configuration and state information that is
 129 kept in the structure
 130 .Ft _res
 131 rather than that referenced through
 132 .Ft statp .
 133 .Pp
 134 Most of the values in
 135 .Ft statp
 136 and
 137 .Ft _res
 138 are initialized on the first call to
 139 .Fn res_ninit
 140 /
 141 .Fn res_init
 142 to reasonable defaults and can be ignored.
 143 Options
 144 stored in
 145 .Ft statp->options
 146 /
 147 .Ft _res.options
 148 are defined in
 149 .Pa resolv.h
 150 and are as follows.
 151 Options are stored as a simple bit mask containing the bitwise
 152 .Dq OR
 153 of the options enabled.
 154 .Bl -tag -width "RES_DEB"
 155 .It Dv RES_INIT
 156 True if the initial name server address and default domain name are
 157 initialized (i.e.,
 158 .Fn res_ninit
 159 /
 160 .Fn res_init
 161 has been called).
 162 .It Dv RES_DEBUG
 163 Print debugging messages.
 164 .It Dv RES_AAONLY
 165 Accept authoritative answers only.
 166 should continue until it finds an authoritative answer or finds an error.
 167 Currently this is not implemented.
 168 .It Dv RES_USEVC
 169 Use TCP connections for queries instead of UDP datagrams.
 170 .It Dv RES_STAYOPEN
 171 Used with
 172 .Dv RES_USEVC
 173 to keep the TCP connection open between queries.
 174 This is useful only in programs that regularly do many queries.
 175 UDP should be the normal mode used.
 176 .It Dv RES_IGNTC
 177 Ignore truncation errors, i.e., don't retry with TCP.
 178 .It Dv RES_RECURSE
 179 Set the recursion-desired bit in queries.
 180 This is the default.
 181 (\c
 182 .Fn res_nsend
 183 /
 184 .Fn res_send
 185 does not do iterative queries and expects the name server
 186 to handle recursion.)
 187 .It Dv RES_DEFNAMES
 188 If set,
 189 .Fn res_nsearch
 190 /
 191 .Fn res_search
 192 will append the default domain name to single-component names
 193 (those that do not contain a dot).
 194 This option is enabled by default.
 195 .It Dv RES_DNSRCH
 196 If this option is set,
 197 .Fn res_nsearch
 198 /
 199 .Fn res_search
 200 will search for host names in the current domain and in parent domains; see
 201 .Xr hostname 7 .
 202 This is used by the standard host lookup routine
 203 .Xr gethostbyname 3 .
 204 This option is enabled by default.
 205 .It Dv RES_NOALIASES
 206 This option turns off the user level aliasing feature controlled by
 207 the
 208 .Ev HOSTALIASES
 209 environment variable.
 210 Network daemons should set this option.
 211 .It Dv RES_USE_INET6
 212 This option causes
 213 .Xr gethostbyname 3
 214 to look for AAAA records before looking for A records if none are found.
 215 .It Dv RES_ROTATE
 216 This options causes the
 217 .Fn res_nsend
 218 /
 219 .Fn res_send
 220 to rotate the list of nameservers in
 221 .Fa statp->nsaddr_list
 222 /
 223 .Fa _res.nsaddr_list .
 224 .It Dv RES_KEEPTSIG
 225 This option causes
 226 .Fn res_nsendsigned
 227 to leave the message unchanged after TSIG verification; otherwise the TSIG
 228 record would be removed and the header updated.
 229 .El
 230 .Pp
 231 The
 232 .Fn res_ninit
 233 /
 234 .Fn res_init
 235 routine
 236 reads the configuration file (if any; see
 237 .Xr resolver 5 )
 238 to get the default domain name, search list and
 239 the Internet address of the local name server(s).
 240 If no server is configured, the host running the resolver is tried.
 241 The current domain name is defined by the hostname
 242 if not specified in the configuration file;
 243 it can be overridden by the environment variable
 244 .Ev LOCALDOMAIN .
 245 This environment variable may contain several blank-separated
 246 tokens if you wish to override the
 247 .Dq search list
 248 on a per-process basis.  This is similar to the
 249 .Ic search
 250 command in the configuration file.
 251 Another environment variable
 252 .Pq Dq Ev RES_OPTIONS
 253 can be set to override certain internal resolver options which are otherwise
 254 set by changing fields in the
 255 .Ft statp
 256 /
 257 .Ft _res
 258 structure or are inherited from the configuration file's
 259 .Ic options
 260 command.  The syntax of the
 261 .Dq Ev RES_OPTIONS
 262 environment variable is explained in
 263 .Xr resolver 5 .
 264 Initialization normally occurs on the first call
 265 to one of the other resolver routines.
 266 .Pp
 267 The
 268 .Fn res_nquery
 269 /
 270 .Fn res_query
 271 functions provides interfaces to the server query mechanism.
 272 They constructs a query, sends it to the local server,
 273 awaits a response, and makes preliminary checks on the reply.
 274 The query requests information of the specified
 275 .Fa type
 276 and
 277 .Fa class
 278 for the specified fully-qualified domain name
 279 .Fa dname .
 280 The reply message is left in the
 281 .Fa answer
 282 buffer with length
 283 .Fa anslen
 284 supplied by the caller.
 285 .Fn res_nquery
 286 /
 287 .Fn res_query
 288 return -1 on error or the length of the answer.
 289 .Pp
 290 The
 291 .Fn res_nsearch
 292 /
 293 .Fn res_search
 294 routines make a query and awaits a response like
 295 .Fn res_nquery
 296 /
 297 .Fn res_query ,
 298 but in addition, it implements the default and search rules
 299 controlled by the
 300 .Dv RES_DEFNAMES
 301 and
 302 .Dv RES_DNSRCH
 303 options.
 304 It returns the length of the first successful reply which is stored in
 305 .Ft answer
 306 or -1 on error.
 307 .Pp
 308 The remaining routines are lower-level routines used by
 309 .Fn res_nquery
 310 /
 311 .Fn res_query .
 312 The
 313 .Fn res_nmkquery
 314 /
 315 .Fn res_mkquery
 316 functions
 317 constructs a standard query message and places it in
 318 .Fa buf .
 319 It returns the size of the query, or \-1 if the query is
 320 larger than
 321 .Fa buflen .
 322 The query type
 323 .Fa op
 324 is usually
 325 .Dv QUERY ,
 326 but can be any of the query types defined in
 327 .Pa <arpa/nameser.h> .
 328 The domain name for the query is given by
 329 .Fa dname .
 330 .Fa Newrr
 331 is currently unused but is intended for making update messages.
 332 .Pp
 333 The
 334 .Fn res_nsend
 335 /
 336 .Fn res_send
 337 /
 338 .Fn res_nsendsigned
 339 routines
 340 sends a pre-formatted query and returns an answer.
 341 It will call
 342 .Fn res_ninit
 343 /
 344 .Fn res_init
 345 if
 346 .Dv RES_INIT
 347 is not set, send the query to the local name server, and
 348 handle timeouts and retries.  Additionally,
 349 .Fn res_nsendsigned
 350 will use TSIG signatures to add authentication to the query and verify the
 351 response.  In this case, only one nameserver will be contacted.
 352 The length of the reply message is returned, or \-1 if there were errors.
 353 .Pp
 354 .Fn res_nquery
 355 /
 356 .Fn res_query ,
 357 .Fn res_nsearch
 358 /
 359 .Fn res_search
 360 and
 361 .Fn res_nsend
 362 /
 363 .Fn res_send
 364 return a length that may be bigger than
 365 .Fa anslen .
 366 In that case the query should be retried with a bigger buffer.
 367 NOTE the answer to the second query may be larger still so supplying
 368 a buffer that bigger that the answer returned by the previous
 369 query is recommended.
 370 .Pp
 371 .Fa answer
 372 MUST be big enough to receive a maximum UDP response from the server or
 373 parts of the answer will be silently discarded.
 374 The default maximum UDP response size is 512 bytes.
 375 .Pp
 376 The function
 377 .Fn res_ourserver_p
 378 returns true when
 379 .Fa inp
 380 is one of the servers in
 381 .Fa statp->nsaddr_list
 382 /
 383 .Fa _res.nsaddr_list .
 384 .Pp
 385 The functions
 386 .Fn fp_nquery
 387 /
 388 .Fn p_query
 389 print out the query and any answer in
 390 .Fa msg
 391 on
 392 .Fa fp .
 393 .Fn p_query
 394 is equivalent to
 395 .Fn fp_nquery
 396 with
 397 .Fa msglen
 398 set to 512.
 399 .Pp
 400 The function
 401 .Fn fp_resstat
 402 prints out the active flag bits in
 403 .Fa statp->options
 404 preceeded by the text ";; res options:" on
 405 .Fa file .
 406 .Pp
 407 The functions
 408 .Fn res_hostalias
 409 /
 410 .Fn hostalias
 411 lookup up name in the file referred to by the
 412 .Ev HOSTALIASES files return a fully qualified hostname if found or NULL if
 413 not found or an error occurred.
 414 .Fn res_hostalias
 415 uses
 416 .Fa buf
 417 to store the result in,
 418 .Fn hostalias
 419 uses a static buffer.
 420 .Pp
 421 The functions
 422 .Fn res_nupdate
 423 /
 424 .Fn res_update
 425 take a list of ns_updrec
 426 .Fa rrecp_in .
 427 Identifies the containing zone for each record and groups the records
 428 according to containing zone maintaining in zone order then sends and update
 429 request to the servers for these zones.  The number of zones updated is
 430 returned or -1 on error.  Note that
 431 .Fn res_nupdate
 432 will perform TSIG authenticated dynamic update operations if the key is not
 433 NULL.
 434 .Pp
 435 The function
 436 .Fn res_findzonecut
 437 discovers the closest enclosing zone cut for a specified domain name,
 438 and finds the IP addresses of the zone's master servers.
 439 .Pp
 440 The functions
 441 .Fn res_nmkupdate
 442 /
 443 .Fn res_mkupdate
 444 take a linked list of ns_updrec
 445 .Fa rrecp_in
 446 and construct a UPDATE message in
 447 .Fa buf .
 448 .Fn res_nmkupdate
 449 /
 450 .Fn res_mkupdate
 451 return the length of the constructed message on no error or one of the
 452 following error values.
 453 .Bl -inset -width "-5"
 454 .It -1
 455 An error occurred parsing
 456 .Fa rrecp_in .
 457 .It -2
 458 The buffer
 459 .Fa buf
 460 was too small.
 461 .It -3
 462 The first record was not a zone section or there was a section order problem.
 463 The section order is S_ZONE, S_PREREQ and S_UPDATE.
 464 .It -4
 465 A number overflow occurred.
 466 .It -5
 467 Unknown operation or no records.
 468 .El
 469 .Pp
 470 The functions
 471 .Fn res_nclose
 472 /
 473 .Fn res_close
 474 close any open files referenced through
 475 .Fa statp
 476 /
 477 .Fa _res .
 478 .Pp
 479 The
 480 .Fn dn_comp
 481 function
 482 compresses the domain name
 483 .Fa exp_dn
 484 and stores it in
 485 .Fa comp_dn .
 486 The size of the compressed name is returned or \-1 if there were errors.
 487 The size of the array pointed to by
 488 .Fa comp_dn
 489 is given by
 490 .Fa length .
 491 The compression uses
 492 an array of pointers
 493 .Fa dnptrs
 494 to previously-compressed names in the current message.
 495 The first pointer points to
 496 to the beginning of the message and the list ends with
 497 .Dv NULL .
 498 The limit to the array is specified by
 499 .Fa lastdnptr .
 500 A side effect of
 501 .Fn dn_comp
 502 is to update the list of pointers for labels inserted into the message
 503 as the name is compressed.  If
 504 .Fa dnptr
 505 is
 506 .Dv NULL ,
 507 names are not compressed.  If
 508 .Fa lastdnptr
 509 is
 510 .Dv NULL ,
 511 the list of labels is not updated.
 512 .Pp
 513 The
 514 .Fn dn_expand
 515 entry
 516 expands the compressed domain name
 517 .Fa comp_dn
 518 to a full domain name.
 519 The compressed name is contained in a query or reply message;
 520 .Fa msg
 521 is a pointer to the beginning of the message.
 522 The uncompressed name is placed in the buffer indicated by
 523 .Fa exp_dn
 524 which is of size
 525 .Fa length .
 526 The size of compressed name is returned or \-1 if there was an error.
 527 .Pp
 528 The variables
 529 .Ft statp->res_h_errno
 530 /
 531 .Ft _res.res_h_errno
 532 and external variable
 533 .Ft h_errno
 534 is set whenever an error occurs during resolver operation.  The following
 535 definitions are given in
 536 .Pa <netdb.h> :
 537 .Bd -literal
 538 #define NETDB_INTERNAL -1  /* see errno */
 539 #define NETDB_SUCCESS  0   /* no problem */
 540 #define HOST_NOT_FOUND 1   /* Authoritative Answer Host not found */
 541 #define TRY_AGAIN      2   /* Non-Authoritative not found, or SERVFAIL */
 542 #define NO_RECOVERY    3   /* Non-Recoverable: FORMERR, REFUSED, NOTIMP */
 543 #define NO_DATA        4   /* Valid name, no data for requested type */
 544 .Ed
 545 .Pp
 546 The
 547 .Fn herror
 548 function writes a message to the diagnostic output consisting of the string
 549 parameter
 550 .Fa s ,
 551 the constant string ": ", and a message corresponding to the value of
 552 .Ft h_errno .
 553 .Pp
 554 The
 555 .Fn hstrerror
 556 function returns a string which is the message text corresponding to the
 557 value of the
 558 .Fa err
 559 parameter.
 560 .Sh FILES
 561 .Bl -tag -width "/etc/resolv.conf    "
 562 .It Pa /etc/resolv.conf
 563 See
 564 .Xr resolver 5 .
 565 .El
 566 .Sh SEE ALSO
 567 .Xr gethostbyname 3 ,
 568 .Xr hostname 7 ,
 569 .Xr named 8 ,
 570 .Xr resolver 5 ;
 571 RFC1032, RFC1033, RFC1034, RFC1035, RFC974;
 572 SMM:11,
 573 .Dq Name Server Operations Guide for Sy BIND