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