| 1 |
'\" t |
| 2 |
.\" Copyright 1993, David Metcalfe <[email protected]> |
| 3 |
.\" Copyright 2015, Michael Kerrisk <[email protected]> |
| 4 |
.\" Copyright, the authors of the Linux man-pages project |
| 5 |
.\" |
| 6 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 7 |
.\" |
| 8 |
.TH resolver 3 2026-02-08 "Linux man-pages 6.18" |
| 9 |
.SH NAME |
| 10 |
res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend, |
| 11 |
res_nclose, |
| 12 |
res_init, res_query, res_search, res_querydomain, res_mkquery, res_send, |
| 13 |
dn_comp, dn_expand \- |
| 14 |
resolver routines |
| 15 |
.SH LIBRARY |
| 16 |
Resolver library |
| 17 |
.RI ( libresolv ,\~ \-lresolv ) |
| 18 |
.SH SYNOPSIS |
| 19 |
.nf |
| 20 |
.B #include <netinet/in.h> |
| 21 |
.B #include <arpa/nameser.h> |
| 22 |
.B #include <resolv.h> |
| 23 |
.P |
| 24 |
.B struct __res_state; |
| 25 |
.B typedef struct __res_state *res_state; |
| 26 |
.P |
| 27 |
.BI "int res_ninit(res_state " statep ); |
| 28 |
.P |
| 29 |
.BI "void res_nclose(res_state " statep ); |
| 30 |
.P |
| 31 |
.BR "int res_nquery(" "int anslen;" |
| 32 |
.BI " res_state " statep , |
| 33 |
.BI " const char *" dname , |
| 34 |
.BI " int " class ", int " type , |
| 35 |
.BI " unsigned char " answer [ anslen "], int " anslen ); |
| 36 |
.P |
| 37 |
.BR "int res_nsearch(" "int anslen;" |
| 38 |
.BI " res_state " statep , |
| 39 |
.BI " const char *" dname , |
| 40 |
.BI " int " class ", int " type , |
| 41 |
.BI " unsigned char " answer [ anslen "], int " anslen ); |
| 42 |
.P |
| 43 |
.BR "int res_nquerydomain(" "int anslen;" |
| 44 |
.BI " res_state " statep , |
| 45 |
.BI " const char *" name ", const char *" domain , |
| 46 |
.BI " int " class ", int " type , |
| 47 |
.BI " unsigned char " answer [ anslen "], int " anslen ); |
| 48 |
.P |
| 49 |
.BR "int res_nmkquery(" "int datalen, int buflen;" |
| 50 |
.BI " res_state " statep ", int " op , |
| 51 |
.BI " const char *" dname , |
| 52 |
.BI " int " class ", int " type , |
| 53 |
.BI " const unsigned char " data [ datalen "], int " datalen , |
| 54 |
.BI " const unsigned char *" newrr , |
| 55 |
.BI " unsigned char " buf [ buflen "], int " buflen ); |
| 56 |
.P |
| 57 |
.BR "int res_nsend(" "int msglen, int anslen;" |
| 58 |
.BI " res_state " statep , |
| 59 |
.BI " const unsigned char " msg [ msglen "], int " msglen , |
| 60 |
.BI " unsigned char " answer [ anslen "], int " anslen ); |
| 61 |
.P |
| 62 |
.BR "int dn_comp(" "int length;" |
| 63 |
.BI " const char *" exp_dn , |
| 64 |
.BI " unsigned char " comp_dn [ length "], int " length , |
| 65 |
.BI " unsigned char **" dnptrs , |
| 66 |
.BI " unsigned char **" lastdnptr ); |
| 67 |
.P |
| 68 |
.BR "int dn_expand(" "int length;" |
| 69 |
.BI " const unsigned char *" msg , |
| 70 |
.BI " const unsigned char *" eomorig , |
| 71 |
.BI " const unsigned char *" comp_dn , |
| 72 |
.BI " char " exp_dn [ length "], int " length ); |
| 73 |
.P |
| 74 |
.B [[deprecated]] extern struct __res_state _res; |
| 75 |
.P |
| 76 |
.B [[deprecated]] int res_init(void); |
| 77 |
.P |
| 78 |
.B [[deprecated]] |
| 79 |
.BR "int res_query(" "int anslen;" |
| 80 |
.BI " const char *" dname , |
| 81 |
.BI " int " class ", int " type , |
| 82 |
.BI " unsigned char " answer [ anslen "], int " anslen ); |
| 83 |
.P |
| 84 |
.B [[deprecated]] |
| 85 |
.BR "int res_search(" "int anslen;" |
| 86 |
.BI " const char *" dname , |
| 87 |
.BI " int " class ", int " type , |
| 88 |
.BI " unsigned char " answer [ anslen "], int " anslen ); |
| 89 |
.P |
| 90 |
.B [[deprecated]] |
| 91 |
.BR "int res_querydomain(" "int anslen;" |
| 92 |
.BI " const char *" name ", const char *" domain , |
| 93 |
.BI " int " class ", int " type , |
| 94 |
.BI " unsigned char " answer [ anslen "], int " anslen ); |
| 95 |
.P |
| 96 |
.B [[deprecated]] |
| 97 |
.BR "int res_mkquery(" "int datalen, int buflen;" |
| 98 |
.BI " int " op , |
| 99 |
.BI " const char *" dname , |
| 100 |
.BI " int " class ", int " type , |
| 101 |
.BI " const unsigned char " data [ datalen "], int " datalen , |
| 102 |
.BI " const unsigned char *" newrr , |
| 103 |
.BI " unsigned char " buf [ buflen "], int " buflen ); |
| 104 |
.P |
| 105 |
.B [[deprecated]] |
| 106 |
.BR "int res_send(" "int msglen, int anslen;" |
| 107 |
.BI " const unsigned char " msg [ msglen "], int " msglen , |
| 108 |
.BI " unsigned char " answer [ anslen "], int " anslen ); |
| 109 |
.fi |
| 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 |
.P |
| 115 |
The functions described below make queries to and interpret |
| 116 |
the responses from Internet domain name servers. |
| 117 |
.P |
| 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 |
.P |
| 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 |
.P |
| 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 |
| 166 |
.I name |
| 167 |
of specified |
| 168 |
.I type |
| 169 |
and |
| 170 |
.IR class . |
| 171 |
The reply is left in the buffer |
| 172 |
.I answer |
| 173 |
of length |
| 174 |
.I anslen |
| 175 |
supplied by the caller. |
| 176 |
.P |
| 177 |
The |
| 178 |
.BR res_nsearch () |
| 179 |
and |
| 180 |
.BR res_search () |
| 181 |
functions make a query and waits for the response like |
| 182 |
.BR res_nquery () |
| 183 |
and |
| 184 |
.BR res_query (), |
| 185 |
but in addition they implement the default and search |
| 186 |
rules controlled by |
| 187 |
.B RES_DEFNAMES |
| 188 |
and |
| 189 |
.B RES_DNSRCH |
| 190 |
(see description of |
| 191 |
.I _res |
| 192 |
options below). |
| 193 |
.P |
| 194 |
The |
| 195 |
.BR res_nquerydomain () |
| 196 |
and |
| 197 |
.BR res_querydomain () |
| 198 |
functions make a query using |
| 199 |
.BR res_nquery ()/ res_query () |
| 200 |
on the concatenation of |
| 201 |
.I name |
| 202 |
and |
| 203 |
.IR domain . |
| 204 |
.P |
| 205 |
The following functions are lower-level routines used by |
| 206 |
.BR res_nquery ()/ res_query (). |
| 207 |
.P |
| 208 |
The |
| 209 |
.BR res_nmkquery () |
| 210 |
and |
| 211 |
.BR res_mkquery () |
| 212 |
functions construct a query message in |
| 213 |
.I buf |
| 214 |
of length |
| 215 |
.I buflen |
| 216 |
for the domain name |
| 217 |
.IR dname . |
| 218 |
The query type |
| 219 |
.I op |
| 220 |
is one of the following (typically |
| 221 |
.BR QUERY ): |
| 222 |
.TP |
| 223 |
.B QUERY |
| 224 |
Standard query. |
| 225 |
.TP |
| 226 |
.B IQUERY |
| 227 |
Inverse query. |
| 228 |
This option was removed in glibc 2.26, |
| 229 |
.\" commit e4e794841e3140875f2aa86b90e2ada3d61e1244 |
| 230 |
since it has not been supported by DNS servers for a very long time. |
| 231 |
.TP |
| 232 |
.B NS_NOTIFY_OP |
| 233 |
Notify secondary of SOA (Start of Authority) change. |
| 234 |
.P |
| 235 |
.I newrr |
| 236 |
is currently unused. |
| 237 |
.P |
| 238 |
The |
| 239 |
.BR res_nsend () |
| 240 |
and |
| 241 |
.BR res_send () |
| 242 |
function send a preformatted query given in |
| 243 |
.I msg |
| 244 |
of length |
| 245 |
.I msglen |
| 246 |
and returns the answer in |
| 247 |
.I answer |
| 248 |
which is of length |
| 249 |
.IR anslen . |
| 250 |
They will call |
| 251 |
.BR res_ninit ()/ res_init () |
| 252 |
if it has not already been called. |
| 253 |
.P |
| 254 |
The |
| 255 |
.BR dn_comp () |
| 256 |
function compresses the domain name |
| 257 |
.I exp_dn |
| 258 |
and stores it in the buffer |
| 259 |
.I comp_dn |
| 260 |
of length |
| 261 |
.IR length . |
| 262 |
The compression uses an array of pointers |
| 263 |
.I dnptrs |
| 264 |
to previously compressed names in the current message. |
| 265 |
The first pointer points |
| 266 |
to the beginning of the message and the list ends with NULL. |
| 267 |
The limit of the array is specified by |
| 268 |
.IR lastdnptr . |
| 269 |
If |
| 270 |
.I dnptr |
| 271 |
is NULL, |
| 272 |
domain names are not compressed. |
| 273 |
If |
| 274 |
.I lastdnptr |
| 275 |
is NULL, |
| 276 |
the list of labels is not updated. |
| 277 |
.P |
| 278 |
The |
| 279 |
.BR dn_expand () |
| 280 |
function expands the compressed domain name |
| 281 |
.I comp_dn |
| 282 |
to a full domain name, |
| 283 |
which is placed in the buffer |
| 284 |
.I exp_dn |
| 285 |
of size |
| 286 |
.IR length . |
| 287 |
The compressed name is contained |
| 288 |
in a query or reply message, |
| 289 |
and |
| 290 |
.I msg |
| 291 |
points to the beginning of the message. |
| 292 |
.P |
| 293 |
The resolver routines use configuration and state information |
| 294 |
contained in a |
| 295 |
.I __res_state |
| 296 |
structure (either passed as the |
| 297 |
.I statep |
| 298 |
argument, or in the global variable |
| 299 |
.IR _res , |
| 300 |
in the case of the older nonreentrant functions). |
| 301 |
The only field of this structure that is normally manipulated by the |
| 302 |
user is the |
| 303 |
.I options |
| 304 |
field. |
| 305 |
This field can contain the bitwise "OR" |
| 306 |
of the following options: |
| 307 |
.TP |
| 308 |
.B RES_INIT |
| 309 |
True if |
| 310 |
.BR res_ninit () |
| 311 |
or |
| 312 |
.BR res_init () |
| 313 |
has been called. |
| 314 |
.TP |
| 315 |
.B RES_DEBUG |
| 316 |
Print debugging messages. |
| 317 |
This option is available only if glibc was built with debugging enabled, |
| 318 |
.\" See resolv/README. |
| 319 |
.\" Support for RES_DEBUG was made conditional in glibc 2.2. |
| 320 |
which is not the default. |
| 321 |
.TP |
| 322 |
.BR RES_AAONLY " (unimplemented; deprecated in glibc 2.25)" |
| 323 |
Accept authoritative answers only. |
| 324 |
.BR res_send () |
| 325 |
continues until |
| 326 |
it finds an authoritative answer or returns an error. |
| 327 |
This option was present but unimplemented until glibc 2.24; |
| 328 |
since glibc 2.25, it is deprecated, and its usage produces a warning. |
| 329 |
.TP |
| 330 |
.B RES_USEVC |
| 331 |
Use TCP connections for queries rather than UDP datagrams. |
| 332 |
.TP |
| 333 |
.BR RES_PRIMARY " (unimplemented; deprecated in glibc 2.25)" |
| 334 |
Query primary domain name server only. |
| 335 |
This option was present but unimplemented until glibc 2.24; |
| 336 |
since glibc 2.25, it is deprecated, and its usage produces a warning. |
| 337 |
.TP |
| 338 |
.B RES_IGNTC |
| 339 |
Ignore truncation errors. |
| 340 |
Don't retry with TCP. |
| 341 |
.TP |
| 342 |
.B RES_RECURSE |
| 343 |
Set the recursion desired bit in queries. |
| 344 |
Recursion is carried out |
| 345 |
by the domain name server, not by |
| 346 |
.BR res_send (). |
| 347 |
[Enabled by default]. |
| 348 |
.TP |
| 349 |
.B RES_DEFNAMES |
| 350 |
If set, |
| 351 |
.BR res_search () |
| 352 |
will append the default domain name to |
| 353 |
single component names\[em]that is, those that do not contain a dot. |
| 354 |
[Enabled by default]. |
| 355 |
.TP |
| 356 |
.B RES_STAYOPEN |
| 357 |
Used with |
| 358 |
.B RES_USEVC |
| 359 |
to keep the TCP connection open between queries. |
| 360 |
.TP |
| 361 |
.B RES_DNSRCH |
| 362 |
If set, |
| 363 |
.BR res_search () |
| 364 |
will search for hostnames in the current |
| 365 |
domain and in parent domains. |
| 366 |
This option is used by |
| 367 |
.BR gethostbyname (3). |
| 368 |
[Enabled by default]. |
| 369 |
.TP |
| 370 |
.B RES_INSECURE1 |
| 371 |
Accept a response from a wrong server. |
| 372 |
This can be used to detect potential security hazards, |
| 373 |
but you need to compile glibc with debugging enabled and use |
| 374 |
.B RES_DEBUG |
| 375 |
option (for debug purpose only). |
| 376 |
.TP |
| 377 |
.B RES_INSECURE2 |
| 378 |
Accept a response which contains a wrong query. |
| 379 |
This can be used to detect potential security hazards, |
| 380 |
but you need to compile glibc with debugging enabled and use |
| 381 |
.B RES_DEBUG |
| 382 |
option (for debug purpose only). |
| 383 |
.TP |
| 384 |
.B RES_NOALIASES |
| 385 |
Disable usage of |
| 386 |
.B HOSTALIASES |
| 387 |
environment variable. |
| 388 |
.TP |
| 389 |
.B RES_USE_INET6 |
| 390 |
Try an AAAA query before an A query inside the |
| 391 |
.BR gethostbyname (3) |
| 392 |
function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records |
| 393 |
are found but an A record set exists. |
| 394 |
Since glibc 2.25, this option is deprecated, |
| 395 |
and its usage produces a warning; |
| 396 |
applications should use |
| 397 |
.BR getaddrinfo (3), |
| 398 |
rather than |
| 399 |
.BR gethostbyname (3). |
| 400 |
.TP |
| 401 |
.B RES_ROTATE |
| 402 |
Causes round-robin selection of name servers from among those listed. |
| 403 |
This has the effect of spreading the query load among all listed servers, |
| 404 |
rather than having all clients try the first listed server first every |
| 405 |
time. |
| 406 |
.TP |
| 407 |
.BR RES_NOCHECKNAME " (unimplemented; deprecated in glibc 2.25)" |
| 408 |
Disable the modern BIND checking of incoming hostnames and mail names |
| 409 |
for invalid characters such as underscore (_), non-ASCII, |
| 410 |
or control characters. |
| 411 |
This option was present until glibc 2.24; |
| 412 |
since glibc 2.25, it is deprecated, and its usage produces a warning. |
| 413 |
.TP |
| 414 |
.BR RES_KEEPTSIG " (unimplemented; deprecated in glibc 2.25)" |
| 415 |
Do not strip TSIG records. |
| 416 |
This option was present but unimplemented until glibc 2.24; |
| 417 |
since glibc 2.25, it is deprecated, and its usage produces a warning. |
| 418 |
.TP |
| 419 |
.BR RES_BLAST " (unimplemented; deprecated in glibc 2.25)" |
| 420 |
Send each query simultaneously and recursively to all servers. |
| 421 |
This option was present but unimplemented until glibc 2.24; |
| 422 |
since glibc 2.25, it is deprecated, and its usage produces a warning. |
| 423 |
.TP |
| 424 |
.BR RES_USEBSTRING " (glibc 2.3.4 to glibc 2.24)" |
| 425 |
Make reverse IPv6 lookups using the bit-label format described in RFC 2673; |
| 426 |
if this option is not set (which is the default), then nibble format is used. |
| 427 |
This option was removed in glibc 2.25, |
| 428 |
since it relied on a backward-incompatible |
| 429 |
DNS extension that was never deployed on the Internet. |
| 430 |
.TP |
| 431 |
.BR RES_NOIP6DOTINT " (glibc 2.24 and earlier)" |
| 432 |
Use |
| 433 |
.I ip6.arpa |
| 434 |
zone in IPv6 reverse lookup instead of |
| 435 |
.IR ip6.int , |
| 436 |
which is deprecated since glibc 2.3.4. |
| 437 |
This option is present up to and including glibc 2.24, |
| 438 |
where it is enabled by default. |
| 439 |
In glibc 2.25, this option was removed. |
| 440 |
.TP |
| 441 |
.BR RES_USE_EDNS0 " (since glibc 2.6)" |
| 442 |
Enables support for the DNS extensions (EDNS0) described in RFC 2671. |
| 443 |
.TP |
| 444 |
.BR RES_SNGLKUP " (since glibc 2.10)" |
| 445 |
By default, glibc performs IPv4 and IPv6 lookups in parallel |
| 446 |
since glibc 2.9. |
| 447 |
Some appliance DNS servers cannot handle these queries properly |
| 448 |
and make the requests time out. |
| 449 |
This option disables the behavior and makes glibc |
| 450 |
perform the IPv6 and IPv4 requests sequentially |
| 451 |
(at the cost of some slowdown of the resolving process). |
| 452 |
.TP |
| 453 |
.B RES_SNGLKUPREOP |
| 454 |
When |
| 455 |
.B RES_SNGLKUP |
| 456 |
option is enabled, opens a new socket for the each request. |
| 457 |
.TP |
| 458 |
.B RES_USE_DNSSEC |
| 459 |
Use DNSSEC with OK bit in OPT record. |
| 460 |
This option implies |
| 461 |
.BR RES_USE_EDNS0 . |
| 462 |
.TP |
| 463 |
.B RES_NOTLDQUERY |
| 464 |
Do not look up unqualified name as a top-level domain (TLD). |
| 465 |
.TP |
| 466 |
.B RES_DEFAULT |
| 467 |
Default option which implies: |
| 468 |
.BR RES_RECURSE , |
| 469 |
.BR RES_DEFNAMES , |
| 470 |
.BR RES_DNSRCH , |
| 471 |
and |
| 472 |
.BR RES_NOIP6DOTINT . |
| 473 |
.\" |
| 474 |
.SH RETURN VALUE |
| 475 |
The |
| 476 |
.BR res_ninit () |
| 477 |
and |
| 478 |
.BR res_init () |
| 479 |
functions return 0 on success, or \-1 if an error |
| 480 |
occurs. |
| 481 |
.P |
| 482 |
The |
| 483 |
.BR res_nquery (), |
| 484 |
.BR res_query (), |
| 485 |
.BR res_nsearch (), |
| 486 |
.BR res_search (), |
| 487 |
.BR res_nquerydomain (), |
| 488 |
.BR res_querydomain (), |
| 489 |
.BR res_nmkquery (), |
| 490 |
.BR res_mkquery (), |
| 491 |
.BR res_nsend (), |
| 492 |
and |
| 493 |
.BR res_send () |
| 494 |
functions return the length |
| 495 |
of the response, or \-1 if an error occurs. |
| 496 |
.P |
| 497 |
The |
| 498 |
.BR dn_comp () |
| 499 |
and |
| 500 |
.BR dn_expand () |
| 501 |
functions return the length |
| 502 |
of the compressed name, or \-1 if an error occurs. |
| 503 |
.P |
| 504 |
In the case of an error return from |
| 505 |
.BR res_nquery (), |
| 506 |
.BR res_query (), |
| 507 |
.BR res_nsearch (), |
| 508 |
.BR res_search (), |
| 509 |
.BR res_nquerydomain (), |
| 510 |
or |
| 511 |
.BR res_querydomain (), |
| 512 |
the global variable |
| 513 |
.I h_errno |
| 514 |
(see |
| 515 |
.BR gethostbyname (3)) |
| 516 |
can be consulted to determine the error. |
| 517 |
.SH FILES |
| 518 |
.TP |
| 519 |
.I /etc/resolv.conf |
| 520 |
resolver configuration file |
| 521 |
.TP |
| 522 |
.I /etc/host.conf |
| 523 |
resolver configuration file |
| 524 |
.SH ATTRIBUTES |
| 525 |
For an explanation of the terms used in this section, see |
| 526 |
.BR attributes (7). |
| 527 |
.TS |
| 528 |
allbox; |
| 529 |
lbx lb lb |
| 530 |
l l l. |
| 531 |
Interface Attribute Value |
| 532 |
T{ |
| 533 |
.na |
| 534 |
.nh |
| 535 |
.BR res_ninit (), |
| 536 |
.BR res_nclose (), |
| 537 |
.BR res_nquery (), |
| 538 |
.BR res_nsearch (), |
| 539 |
.BR res_nquerydomain (), |
| 540 |
.BR res_nsend () |
| 541 |
T} Thread safety MT-Safe locale |
| 542 |
T{ |
| 543 |
.na |
| 544 |
.nh |
| 545 |
.BR res_nmkquery (), |
| 546 |
.BR dn_comp (), |
| 547 |
.BR dn_expand () |
| 548 |
T} Thread safety MT-Safe |
| 549 |
.TE |
| 550 |
.SH STANDARDS |
| 551 |
None. |
| 552 |
.SH HISTORY |
| 553 |
4.3BSD. |
| 554 |
.SH SEE ALSO |
| 555 |
.BR gethostbyname (3), |
| 556 |
.BR resolv.conf (5), |
| 557 |
.BR resolver (5), |
| 558 |
.BR hostname (7), |
| 559 |
.BR named (8) |
| 560 |
.P |
| 561 |
The GNU C library source file |
| 562 |
.IR resolv/README . |