Debian Codegraph @

upstream/debian-unstable/man3/resolver.3

raw
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 .