2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
3 .\" and (C) Copyright 2015 Michael Kerrisk <mtk.manpages@gmail.com>
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\" References consulted:
8 .\" Linux libc source code
9 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
11 .\" Modified 1993-07-25 by Rik Faith (faith@cs.unc.edu)
12 .\" Modified 2004-10-31 by aeb
14 .TH resolver 3 (date) "Linux man-pages (unreleased)"
16 res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend,
18 res_init, res_query, res_search, res_querydomain, res_mkquery, res_send,
23 .RI ( libresolv ", " \-lresolv )
26 .B #include <netinet/in.h>
27 .B #include <arpa/nameser.h>
28 .B #include <resolv.h>
30 .B struct __res_state;
31 .B typedef struct __res_state *res_state;
33 .BI "int res_ninit(res_state " statep );
35 .BI "void res_nclose(res_state " statep );
37 .BI "int res_nquery(res_state " statep ,
38 .BI " const char *" dname ", int " class ", int " type ,
39 .BI " unsigned char " answer [. anslen "], int " anslen );
41 .BI "int res_nsearch(res_state " statep ,
42 .BI " const char *" dname ", int " class ", int " type ,
43 .BI " unsigned char " answer [. anslen "], int " anslen );
45 .BI "int res_nquerydomain(res_state " statep ,
46 .BI " const char *" name ", const char *" domain ,
47 .BI " int " class ", int " type ", unsigned char " answer [. anslen ],
50 .BI "int res_nmkquery(res_state " statep ,
51 .BI " int " op ", const char *" dname ", int " class ,
52 .BI " int " type ", const unsigned char " data [. datalen "], \
54 .BI " const unsigned char *" newrr ,
55 .BI " unsigned char " buf [. buflen "], int " buflen );
57 .BI "int res_nsend(res_state " statep ,
58 .BI " const unsigned char " msg [. msglen "], int " msglen ,
59 .BI " unsigned char " answer [. anslen "], int " anslen );
61 .BI "int dn_comp(const char *" exp_dn ", unsigned char " comp_dn [. length ],
62 .BI " int " length ", unsigned char **" dnptrs ,
63 .BI " unsigned char **" lastdnptr );
65 .BI "int dn_expand(const unsigned char *" msg ,
66 .BI " const unsigned char *" eomorig ,
67 .BI " const unsigned char *" comp_dn ", char " exp_dn [. length ],
70 .B [[deprecated]] extern struct __res_state _res;
72 .B [[deprecated]] int res_init(void);
75 .BI "int res_query(const char *" dname ", int " class ", int " type ,
76 .BI " unsigned char " answer [. anslen "], int " anslen );
79 .BI "int res_search(const char *" dname ", int " class ", int " type ,
80 .BI " unsigned char " answer [. anslen "], int " anslen );
83 .BI "int res_querydomain(const char *" name ", const char *" domain ,
84 .BI " int " class ", int " type ", unsigned char " answer [. anslen ],
88 .BI "int res_mkquery(int " op ", const char *" dname ", int " class ,
89 .BI " int " type ", const unsigned char " data [. datalen "], \
91 .BI " const unsigned char *" newrr ,
92 .BI " unsigned char " buf [. buflen "], int " buflen );
95 .BI "int res_send(const unsigned char " msg [. msglen "], int " msglen ,
96 .BI " unsigned char " answer [. anslen "], int " anslen );
100 This page is incomplete (various resolver functions provided by glibc
101 are not described) and likely out of date.
103 The functions described below make queries to and interpret
104 the responses from Internet domain name servers.
106 The API consists of a set of more modern, reentrant functions
107 and an older set of nonreentrant functions that have been superseded.
108 The traditional resolver interfaces such as
112 use some static (global) state stored in the
114 structure, rendering these functions non-thread-safe.
115 BIND 8.2 introduced a set of new interfaces
118 and so on, which take a
120 as their first argument, so you can use a per-thread resolver state.
126 functions read the configuration files (see
128 to get the default domain name and name
130 If no server is given, the local host is tried.
131 If no domain is given, that associated with the local host is used.
132 It can be overridden with the environment variable
137 is normally executed by the first call to one of the
141 requires a corresponding call to
143 to free memory allocated by
145 and subsequent calls to
152 functions query the name server for the
153 fully qualified domain name \fIname\fP of specified \fItype\fP and
155 The reply is left in the buffer \fIanswer\fP of length
156 \fIanslen\fP supplied by the caller.
162 functions make a query and waits for the response like
166 but in addition they implement the default and search
172 \fI_res\fP options below).
175 .BR res_nquerydomain ()
177 .BR res_querydomain ()
178 functions make a query using
179 .BR res_nquery ()/ res_query ()
180 on the concatenation of \fIname\fP and \fIdomain\fP.
182 The following functions are lower-level routines used by
183 .BR res_nquery ()/ res_query ().
189 functions construct a query message in \fIbuf\fP
190 of length \fIbuflen\fP for the domain name \fIdname\fP.
192 \fIop\fP is one of the following (typically
200 This option was removed in glibc 2.26,
201 .\" commit e4e794841e3140875f2aa86b90e2ada3d61e1244
202 since it has not been supported by DNS servers for a very long time.
205 Notify secondary of SOA (Start of Authority) change.
207 \fInewrr\fP is currently unused.
213 function send a preformatted query given in
214 \fImsg\fP of length \fImsglen\fP and returns the answer in \fIanswer\fP
215 which is of length \fIanslen\fP.
217 .BR res_ninit ()/ res_init ()
218 if it has not already been called.
222 function compresses the domain name \fIexp_dn\fP
223 and stores it in the buffer \fIcomp_dn\fP of length \fIlength\fP.
224 The compression uses an array of pointers \fIdnptrs\fP to previously
225 compressed names in the current message.
226 The first pointer points
227 to the beginning of the message and the list ends with NULL.
228 The limit of the array is specified by \fIlastdnptr\fP.
229 If \fIdnptr\fP is NULL, domain names are not compressed.
230 If \fIlastdnptr\fP is NULL, the list
231 of labels is not updated.
235 function expands the compressed domain name
236 \fIcomp_dn\fP to a full domain name, which is placed in the buffer
237 \fIexp_dn\fP of size \fIlength\fP.
238 The compressed name is contained
239 in a query or reply message, and \fImsg\fP points to the beginning of
242 The resolver routines use configuration and state information
245 structure (either passed as the
247 argument, or in the global variable
249 in the case of the older nonreentrant functions).
250 The only field of this structure that is normally manipulated by the
254 This field can contain the bitwise "OR"
255 of the following options:
265 Print debugging messages.
266 This option is available only if glibc was built with debugging enabled,
267 .\" See resolv/README.
268 .\" Support for RES_DEBUG was made conditional in glibc 2.2.
269 which is not the default.
271 .BR RES_AAONLY " (unimplemented; deprecated in glibc 2.25)"
272 Accept authoritative answers only.
275 it finds an authoritative answer or returns an error.
276 This option was present but unimplemented until glibc 2.24;
277 since glibc 2.25, it is deprecated, and its usage produces a warning.
280 Use TCP connections for queries rather than UDP datagrams.
282 .BR RES_PRIMARY " (unimplemented; deprecated in glibc 2.25)"
283 Query primary domain name server only.
284 This option was present but unimplemented until glibc 2.24;
285 since glibc 2.25, it is deprecated, and its usage produces a warning.
288 Ignore truncation errors.
289 Don't retry with TCP.
292 Set the recursion desired bit in queries.
293 Recursion is carried out
294 by the domain name server, not by
296 [Enabled by default].
301 will append the default domain name to
302 single component names\[em]that is, those that do not contain a dot.
303 [Enabled by default].
308 to keep the TCP connection open between queries.
313 will search for hostnames in the current
314 domain and in parent domains.
315 This option is used by
316 .BR gethostbyname (3).
317 [Enabled by default].
320 Accept a response from a wrong server.
321 This can be used to detect potential security hazards,
322 but you need to compile glibc with debugging enabled and use
324 option (for debug purpose only).
327 Accept a response which contains a wrong query.
328 This can be used to detect potential security hazards,
329 but you need to compile glibc with debugging enabled and use
331 option (for debug purpose only).
336 environment variable.
339 Try an AAAA query before an A query inside the
340 .BR gethostbyname (3)
341 function, and map IPv4 responses in IPv6 "tunneled form" if no AAAA records
342 are found but an A record set exists.
343 Since glibc 2.25, this option is deprecated,
344 and its usage produces a warning;
345 applications should use
348 .BR gethostbyname (3).
351 Causes round-robin selection of name servers from among those listed.
352 This has the effect of spreading the query load among all listed servers,
353 rather than having all clients try the first listed server first every
356 .BR RES_NOCHECKNAME " (unimplemented; deprecated in glibc 2.25)"
357 Disable the modern BIND checking of incoming hostnames and mail names
358 for invalid characters such as underscore (_), non-ASCII,
359 or control characters.
360 This option was present until glibc 2.24;
361 since glibc 2.25, it is deprecated, and its usage produces a warning.
363 .BR RES_KEEPTSIG " (unimplemented; deprecated in glibc 2.25)"
364 Do not strip TSIG records.
365 This option was present but unimplemented until glibc 2.24;
366 since glibc 2.25, it is deprecated, and its usage produces a warning.
368 .BR RES_BLAST " (unimplemented; deprecated in glibc 2.25)"
369 Send each query simultaneously and recursively to all servers.
370 This option was present but unimplemented until glibc 2.24;
371 since glibc 2.25, it is deprecated, and its usage produces a warning.
373 .BR RES_USEBSTRING " (glibc 2.3.4 to glibc 2.24)"
374 Make reverse IPv6 lookups using the bit-label format described in RFC 2673;
375 if this option is not set (which is the default), then nibble format is used.
376 This option was removed in glibc 2.25,
377 since it relied on a backward-incompatible
378 DNS extension that was never deployed on the Internet.
380 .BR RES_NOIP6DOTINT " (glibc 2.24 and earlier)"
383 zone in IPv6 reverse lookup instead of
385 which is deprecated since glibc 2.3.4.
386 This option is present up to and including glibc 2.24,
387 where it is enabled by default.
388 In glibc 2.25, this option was removed.
390 .BR RES_USE_EDNS0 " (since glibc 2.6)"
391 Enables support for the DNS extensions (EDNS0) described in RFC 2671.
393 .BR RES_SNGLKUP " (since glibc 2.10)"
394 By default, glibc performs IPv4 and IPv6 lookups in parallel
396 Some appliance DNS servers cannot handle these queries properly
397 and make the requests time out.
398 This option disables the behavior and makes glibc
399 perform the IPv6 and IPv4 requests sequentially
400 (at the cost of some slowdown of the resolving process).
405 option is enabled, opens a new socket for the each request.
408 Use DNSSEC with OK bit in OPT record.
413 Do not look up unqualified name as a top-level domain (TLD).
416 Default option which implies:
421 .BR RES_NOIP6DOTINT .
428 functions return 0 on success, or \-1 if an error
436 .BR res_nquerydomain (),
437 .BR res_querydomain (),
443 functions return the length
444 of the response, or \-1 if an error occurs.
450 functions return the length
451 of the compressed name, or \-1 if an error occurs.
453 In the case of an error return from
458 .BR res_nquerydomain (),
460 .BR res_querydomain (),
464 .BR gethostbyname (3))
465 can be consulted to determine the cause of the error.
469 resolver configuration file
472 resolver configuration file
474 For an explanation of the terms used in this section, see
482 Interface Attribute Value
488 .BR res_nquerydomain (),
490 T} Thread safety MT-Safe locale
495 T} Thread safety MT-Safe
503 .BR gethostbyname (3),
509 The GNU C library source file