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