man3/resolver.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and (C) Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" References consulted:
  27 .\"     Linux libc source code
  28 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  29 .\"     386BSD man pages
  30 .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu)
  31 .\" Modified 2004-10-31 by aeb
  32 .\"
  33 .TH RESOLVER 3 2017-09-15 "GNU" "Linux Programmer's Manual"
  34 .SH NAME
  35 res_ninit, res_nclose, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend,
  36 res_init, res_query, res_search, res_querydomain, res_mkquery, res_send,
  37 dn_comp, dn_expand \- resolver routines
  38 .SH SYNOPSIS
  39 .nf
  40 .B #include <netinet/in.h>
  41 .B #include <arpa/nameser.h>
  42 .B #include <resolv.h>
  43 .PP
  44 .B struct __res_state;
  45 .B typedef struct __res_state *res_state;
  46 .PP
  47 .BI "int res_ninit(res_state " statep );
  48 .PP
  49 .BI "void res_nclose(res_state " statep );
  50 .PP
  51 .BI "int res_nquery(res_state " statep ,
  52 .BI "           const char *" dname ", int " class ", int " type ,
  53 .BI "           unsigned char *" answer ", int " anslen );
  54 .PP
  55 .BI "int res_nsearch(res_state " statep ,
  56 .BI "           const char *" dname ", int " class ", int " type ,
  57 .BI "           unsigned char *" answer ", int " anslen );
  58 .PP
  59 .BI "int res_nquerydomain(res_state " statep ,
  60 .BI "           const char *" name ", const char *" domain ,
  61 .BI "           int " class ", int " type ", unsigned char *" answer ,
  62 .BI "           int " anslen );
  63 .PP
  64 .BI "int res_nmkquery(res_state " statep ,
  65 .BI "           int " op ", const char *" dname ", int " class ,
  66 .BI "           int " type ", const unsigned char *" data ", int " datalen ,
  67 .BI "           const unsigned char *" newrr ,
  68 .BI "           unsigned char *" buf ", int " buflen );
  69 .PP
  70 .BI "int res_nsend(res_state " statep ,
  71 .BI "           const unsigned char *" msg ", int " msglen ,
  72 .BI "           unsigned char *" answer ", int " anslen );
  73 .PP
  74 .BI "int dn_comp(const char *" exp_dn ", unsigned char *" comp_dn ,
  75 .BI "           int " length ", unsigned char **" dnptrs ,
  76 .BI "           unsigned char **" lastdnptr );
  77 .PP
  78 .BI "int dn_expand(const unsigned char *" msg ,
  79 .BI "           const unsigned char *" eomorig ,
  80 .BI "           const unsigned char *" comp_dn ", char *" exp_dn ,
  81 .BI "           int " length );
  82 .fi
  83 .\"
  84 .SS Deprecated
  85 .nf
  86 .B extern struct __res_state _res;
  87 .PP
  88 .B int res_init(void);
  89 .PP
  90 .BI "int res_query(const char *" dname ", int " class ", int " type ,
  91 .BI "           unsigned char *" answer ", int " anslen );
  92 .PP
  93 .BI "int res_search(const char *" dname ", int " class ", int " type ,
  94 .BI "           unsigned char *" answer ", int " anslen );
  95 .PP
  96 .BI "int res_querydomain(const char *" name ", const char *" domain ,
  97 .BI "           int " class ", int " type ", unsigned char *" answer ,
  98 .BI "           int " anslen );
  99 .PP
 100 .BI "int res_mkquery(int " op ", const char *" dname ", int " class ,
 101 .BI "           int " type ", const unsigned char *" data ", int " datalen ,
 102 .BI "           const unsigned char *" newrr ,
 103 .BI "           unsigned char *" buf ", int " buflen );
 104 .PP
 105 .BI "int res_send(const unsigned char *" msg ", int " msglen ,
 106 .BI "           unsigned char *" answer ", int " anslen );
 107 .fi
 108 .PP
 109 Link with \fI\-lresolv\fP.
 110 .SH DESCRIPTION
 111 .B Note:
 112 This page is incomplete (various resolver functions provided by glibc
 113 are not described) and likely out of date.
 114 .PP
 115 The functions described below make queries to and interpret
 116 the responses from Internet domain name servers.
 117 .PP
 118 The API consists of a set of more modern, reentrant functions
 119 and an older set of nonreentrant functions that have been superseded.
 120 The traditional resolver interfaces such as
 121 .BR res_init ()
 122 and
 123 .BR res_query ()
 124 use some static (global) state stored in the
 125 .I _res
 126 structure, rendering these functions non-thread-safe.
 127 BIND 8.2 introduced a set of new interfaces
 128 .BR res_ninit (),
 129 .BR res_nquery (),
 130 and so on, which take a
 131 .I res_state
 132 as their first argument, so you can use a per-thread resolver state.
 133 .PP
 134 The
 135 .BR res_ninit ()
 136 and
 137 .BR res_init ()
 138 functions read the configuration files (see
 139 .BR resolv.conf (5))
 140 to get the default domain name and name
 141 server address(es).
 142 If no server is given, the local host is tried.
 143 If no domain is given, that associated with the local host is used.
 144 It can be overridden with the environment variable
 145 .BR LOCALDOMAIN .
 146 .BR res_ninit ()
 147 or
 148 .BR res_init ()
 149 is normally executed by the first call to one of the
 150 other functions.
 151 Every call to
 152 .BR res_ninit ()
 153 requires a corresponding call to
 154 .BR res_nclose ()
 155 to free memory allocated by
 156 .BR res_ninit ()
 157 and subsequent calls to
 158 .BR res_nquery ().
 159 .PP
 160 The
 161 .BR res_nquery ()
 162 and
 163 .BR res_query ()
 164 functions query the name server for the
 165 fully qualified domain name \fIname\fP of specified \fItype\fP and
 166 \fIclass\fP.
 167 The reply is left in the buffer \fIanswer\fP of length
 168 \fIanslen\fP supplied by the caller.
 169 .PP
 170 The
 171 .BR res_nsearch ()
 172 and
 173 .BR res_search ()
 174 functions make a query and waits for the response like
 175 .BR res_nquery ()
 176 and
 177 .BR res_query (),
 178 but in addition they implement the default and search
 179 rules controlled by
 180 .B RES_DEFNAMES
 181 and
 182 .B RES_DNSRCH
 183 (see description of
 184 \fI_res\fP options below).
 185 .PP
 186 The
 187 .BR res_nquerydomain ()
 188 and
 189 .BR res_querydomain ()
 190 functions make a query using
 191 .BR res_nquery ()/ res_query ()
 192 on the concatenation of \fIname\fP and \fIdomain\fP.
 193 .PP
 194 The following functions are lower-level routines used by
 195 .BR res_query ()/ res_query ().
 196 .PP
 197 The
 198 .BR res_nmkquery ()
 199 and
 200 .BR res_mkquery ()
 201 functions construct a query message in \fIbuf\fP
 202 of length \fIbuflen\fP for the domain name \fIdname\fP.
 203 The query type
 204 \fIop\fP is one of the following (typically
 205 .BR QUERY ):
 206 .TP
 207 .B QUERY
 208 Standard query.
 209 .TP
 210 .B IQUERY
 211 Inverse query.
 212 This option was removed in glibc 2.26,
 213 .\" commit e4e794841e3140875f2aa86b90e2ada3d61e1244
 214 since it has not been supported by DNS servers for a very long time.
 215 .TP
 216 .B NS_NOTIFY_OP
 217 Notify secondary of SOA (Start of Authority) change.
 218 .PP
 219 \fInewrr\fP is currently unused.
 220 .PP
 221 The
 222 .BR res_nsend ()
 223 and
 224 .BR res_send ()
 225 function send a preformatted query given in
 226 \fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP
 227 which is of length \fIanslen\fP.
 228 They will call
 229 .BR res_ninit ()/ res_init ()
 230 if it has not already been called.
 231 .PP
 232 The
 233 .BR dn_comp ()
 234 function compresses the domain name \fIexp_dn\fP
 235 and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP.
 236 The compression uses an array of pointers \fIdnptrs\fP to previously
 237 compressed names in the current message.
 238 The first pointer points
 239 to the beginning of the message and the list ends with NULL.
 240 The limit of the array is specified by \fIlastdnptr\fP.
 241 If \fIdnptr\fP is NULL, domain names are not compressed.
 242 If \fIlastdnptr\fP is NULL, the list
 243 of labels is not updated.
 244 .PP
 245 The
 246 .BR dn_expand ()
 247 function expands the compressed domain name
 248 \fIcomp_dn\fP to a full domain name, which is placed in the buffer
 249 \fIexp_dn\fP of size \fIlength\fP.
 250 The compressed name is contained
 251 in a query or reply message, and \fImsg\fP points to the beginning of
 252 the message.
 253 .PP
 254 The resolver routines use configuration and state information
 255 contained in a
 256 .IR __res_state
 257 structure (either passed as the
 258 .IR statep
 259 argument, or in the global variable
 260 .IR _res ,
 261 in the case of the older nonreentrant functions).
 262 The only field of this structure that is normally manipulated by the
 263 user is the
 264 .IR options
 265 field.
 266 This field can contain the bitwise "OR"
 267 of the following options:
 268 .TP
 269 .B RES_INIT
 270 True if
 271 .BR res_ninit ()
 272 or
 273 .BR res_init ()
 274 has been called.
 275 .TP
 276 .B RES_DEBUG
 277 Print debugging messages.
 278 This option is available only if glibc was built with debugging enabled,
 279 .\" See resolv/README.
 280 .\" Support for RES_DEBUG was made conditional in glibc 2.2.
 281 which is not the default.
 282 .TP
 283 .BR RES_AAONLY " (unimplemented; deprecated in glibc 2.25)"
 284 Accept authoritative answers only.
 285 .BR res_send ()
 286 continues until
 287 it finds an authoritative answer or returns an error.
 288 This option was present but unimplemented in glibc until version 2.24;
 289 since glibc 2.25, it is deprecated, and its usage produces a warning.
 290 .TP
 291 .B RES_USEVC
 292 Use TCP connections for queries rather than UDP datagrams.
 293 .TP
 294 .BR RES_PRIMARY " (unimplemented; deprecated in glibc 2.25)"
 295 Query primary domain name server only.
 296 This option was present but unimplemented in glibc until version 2.24;
 297 since glibc 2.25, it is deprecated, and its usage produces a warning.
 298 .TP
 299 .B RES_IGNTC
 300 Ignore truncation errors.
 301 Don't retry with TCP.
 302 .TP
 303 .B RES_RECURSE
 304 Set the recursion desired bit in queries.
 305 Recursion is carried out
 306 by the domain name server, not by
 307 .BR res_send ().
 308 [Enabled by default].
 309 .TP
 310 .B RES_DEFNAMES
 311 If set,
 312 .BR res_search ()
 313 will append the default domain name to
 314 single component names\(emthat is, those that do not contain a dot.
 315 [Enabled by default].
 316 .TP
 317 .B RES_STAYOPEN
 318 Used with
 319 .B RES_USEVC
 320 to keep the TCP connection open between queries.
 321 .TP
 322 .B RES_DNSRCH
 323 If set,
 324 .BR res_search ()
 325 will search for hostnames in the current
 326 domain and in parent domains.
 327 This option is used by
 328 .BR gethostbyname (3).
 329 [Enabled by default].
 330 .TP
 331 .B RES_INSECURE1
 332 Accept a response from a wrong server.
 333 This can be used to detect potential security hazards,
 334 but you need to compile glibc with debugging enabled and use
 335 .B RES_DEBUG
 336 option (for debug purpose only).
 337 .TP
 338 .B RES_INSECURE2
 339 Accept a response which contains a wrong query.
 340 This can be used to detect potential security hazards,
 341 but you need to compile glibc with debugging enabled and use
 342 .B RES_DEBUG
 343 option (for debug purpose only).
 344 .TP
 345 .B RES_NOALIASES
 346 Disable usage of
 347 .B HOSTALIASES
 348 environment variable.
 349 .TP
 350 .B RES_USE_INET6
 351 Try an AAAA query before an A query inside the
 352 .BR gethostbyname (3)
 353 function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records
 354 are found but an A record set exists.
 355 Since glibc 2.25, this option is deprecated,
 356 and its usage produces a warning;
 357 applications should use
 358 .BR getaddrinfo (3),
 359 rather than
 360 .BR gethostbyname (3).
 361 .TP
 362 .B RES_ROTATE
 363 Causes round-robin selection of name servers from among those listed.
 364 This has the effect of spreading the query load among all listed servers,
 365 rather than having all clients try the first listed server first every
 366 time.
 367 .TP
 368 .BR RES_NOCHECKNAME " (unimplemented; deprecated in glibc 2.25)"
 369 Disable the modern BIND checking of incoming hostnames and mail names
 370 for invalid characters such as underscore (_), non-ASCII,
 371 or control characters.
 372 This option was present in glibc until version 2.24;
 373 since glibc 2.25, it is deprecated, and its usage produces a warning.
 374 .TP
 375 .BR RES_KEEPTSIG " (unimplemented; deprecated in glibc 2.25)"
 376 Do not strip TSIG records.
 377 This option was present but unimplemented in glibc until version 2.24;
 378 since glibc 2.25, it is deprecated, and its usage produces a warning.
 379 .TP
 380 .B RES_BLAST " (unimplemented; deprecated in glibc 2.25)"
 381 Send each query simultaneously and recursively to all servers.
 382 This option was present but unimplemented in glibc until version 2.24;
 383 since glibc 2.25, it is deprecated, and its usage produces a warning.
 384 .TP
 385 .BR RES_USEBSTRING " (glibc 2.3.4 to 2.24)"
 386 Make reverse IPv6 lookups using the bit-label format described in RFC 2673;
 387 if this option is not set (which is the default), then nibble format is used.
 388 This option was removed in glibc 2.25,
 389 since it relied on a backward-incompatible
 390 DNS extension that was never deployed on the Internet.
 391 .TP
 392 .BR RES_NOIP6DOTINT " (glibc 2.24 and earlier)"
 393 Use
 394 .I ip6.arpa
 395 zone in IPv6 reverse lookup instead of
 396 .IR ip6.int ,
 397 which is deprecated since glibc 2.3.4.
 398 This option is present in glibc up to and including version 2.24,
 399 where it is enabled by default.
 400 In glibc 2.25, this option was removed.
 401 .TP
 402 .BR RES_USE_EDNS0 " (since glibc 2.6)"
 403 Enables support for the DNS extensions (EDNS0) described in RFC 2671.
 404 .TP
 405 .BR RES_SNGLKUP " (since glibc 2.10)"
 406 By default, glibc performs IPv4 and IPv6 lookups in parallel since
 407 version 2.9.
 408 Some appliance DNS servers cannot handle these queries properly
 409 and make the requests time out.
 410 This option disables the behavior and makes glibc
 411 perform the IPv6 and IPv4 requests sequentially
 412 (at the cost of some slowdown of the resolving process).
 413 .TP
 414 .B RES_SNGLKUPREOP
 415 When
 416 .B RES_SNGLKUP
 417 option is enabled, opens a new socket for the each request.
 418 .TP
 419 .B RES_USE_DNSSEC
 420 Use DNSSEC with OK bit in OPT record.
 421 This option implies
 422 .BR RES_USE_EDNS0 .
 423 .TP
 424 .B RES_NOTLDQUERY
 425 Do not look up unqualified name as a top-level domain (TLD).
 426 .TP
 427 .B RES_DEFAULT
 428 Default option which implies:
 429 .BR RES_RECURSE ,
 430 .BR RES_DEFNAMES ,
 431 .BR RES_DNSRCH
 432 and
 433 .BR RES_NOIP6DOTINT .
 434 .\"
 435 .SH RETURN VALUE
 436 The
 437 .BR res_ninit ()
 438 and
 439 .BR res_init ()
 440 functions return 0 on success, or \-1 if an error
 441 occurs.
 442 .PP
 443 The
 444 .BR res_nquery (),
 445 .BR res_query (),
 446 .BR res_nsearch (),
 447 .BR res_search (),
 448 .BR res_nquerydomain (),
 449 .BR res_querydomain (),
 450 .BR res_nmkquery (),
 451 .BR res_mkquery (),
 452 .BR res_nsend (),
 453 and
 454 .BR res_send ()
 455 functions return the length
 456 of the response, or \-1 if an error occurs.
 457 .PP
 458 The
 459 .BR dn_comp ()
 460 and
 461 .BR dn_expand ()
 462 functions return the length
 463 of the compressed name, or \-1 if an error occurs.
 464 .SH FILES
 465 .TP
 466 .I /etc/resolv.conf
 467 resolver configuration file
 468 .TP
 469 .I /etc/host.conf
 470 resolver configuration file
 471 .SH ATTRIBUTES
 472 For an explanation of the terms used in this section, see
 473 .BR attributes (7).
 474 .TS
 475 allbox;
 476 lbw34 lb lb
 477 l l l.
 478 Interface       Attribute       Value
 479 T{
 480 .BR res_ninit (),
 481 .BR res_nclose (),
 482 .BR res_nquery (),
 483 .br
 484 .BR res_nsearch (),
 485 .BR res_nquerydomain (),
 486 .BR res_nsend ()
 487 T}      Thread safety   MT-Safe locale
 488 T{
 489 .BR res_nmkquery (),
 490 .BR dn_comp (),
 491 .br
 492 .BR dn_expand ()
 493 T}      Thread safety   MT-Safe
 494 .TE
 495 .sp 1
 496 .SH CONFORMING TO
 497 4.3BSD.
 498 .SH SEE ALSO
 499 .BR gethostbyname (3),
 500 .BR resolv.conf (5),
 501 .BR resolver (5),
 502 .BR hostname (7),
 503 .BR named (8)
 504 .PP
 505 The GNU C library source file
 506 .IR resolv/README .