1resolver(3) Library Functions Manual resolver(3)
2
6 res_ninit, res_nquery, res_nsearch, res_nquerydomain, res_nmkquery,
7 res_nsend, res_nclose, res_init, res_query, res_search, res_querydo‐
8 main, res_mkquery, res_send, dn_comp, dn_expand - resolver routines
9
11 Resolver library (libresolv, -lresolv)
12
14 #include <netinet/in.h>
15 #include <arpa/nameser.h>
16 #include <resolv.h>
17 struct __res_state;
19 typedef struct __res_state *res_state;
20 int res_ninit(res_state statep);
22 void res_nclose(res_state statep);
24 int res_nquery(res_state statep,
26 const char *dname, int class, int type,
27 unsigned char answer[.anslen], int anslen);
28 int res_nsearch(res_state statep,
30 const char *dname, int class, int type,
31 unsigned char answer[.anslen], int anslen);
32 int res_nquerydomain(res_state statep,
34 const char *name, const char *domain,
35 int class, int type, unsigned char answer[.anslen],
36 int anslen);
37 int res_nmkquery(res_state statep,
39 int op, const char *dname, int class,
40 int type, const unsigned char data[.datalen], int datalen,
41 const unsigned char *newrr,
42 unsigned char buf[.buflen], int buflen);
43 int res_nsend(res_state statep,
45 const unsigned char msg[.msglen], int msglen,
46 unsigned char answer[.anslen], int anslen);
47 int dn_comp(const char *exp_dn, unsigned char comp_dn[.length],
49 int length, unsigned char **dnptrs,
50 unsigned char **lastdnptr);
51 int dn_expand(const unsigned char *msg,
53 const unsigned char *eomorig,
54 const unsigned char *comp_dn, char exp_dn[.length],
55 int length);
56 [[deprecated]] extern struct __res_state _res;
58 [[deprecated]] int res_init(void);
60 [[deprecated]]
62 int res_query(const char *dname, int class, int type,
63 unsigned char answer[.anslen], int anslen);
64 [[deprecated]]
66 int res_search(const char *dname, int class, int type,
67 unsigned char answer[.anslen], int anslen);
68 [[deprecated]]
70 int res_querydomain(const char *name, const char *domain,
71 int class, int type, unsigned char answer[.anslen],
72 int anslen);
73 [[deprecated]]
75 int res_mkquery(int op, const char *dname, int class,
76 int type, const unsigned char data[.datalen], int datalen,
77 const unsigned char *newrr,
78 unsigned char buf[.buflen], int buflen);
79 [[deprecated]]
81 int res_send(const unsigned char msg[.msglen], int msglen,
82 unsigned char answer[.anslen], int anslen);
83
85 Note: This page is incomplete (various resolver functions provided by
86 glibc are not described) and likely out of date.
87 The functions described below make queries to and interpret the re‐
89 sponses from Internet domain name servers.
90 The API consists of a set of more modern, reentrant functions and an
92 older set of nonreentrant functions that have been superseded. The
93 traditional resolver interfaces such as res_init() and res_query() use
94 some static (global) state stored in the _res structure, rendering
95 these functions non-thread-safe. BIND 8.2 introduced a set of new in‐
96 terfaces res_ninit(), res_nquery(), and so on, which take a res_state
97 as their first argument, so you can use a per-thread resolver state.
98 The res_ninit() and res_init() functions read the configuration files
100 (see resolv.conf(5)) to get the default domain name and name server ad‐
101 dress(es). If no server is given, the local host is tried. If no do‐
102 main is given, that associated with the local host is used. It can be
103 overridden with the environment variable LOCALDOMAIN. res_ninit() or
104 res_init() is normally executed by the first call to one of the other
105 functions. Every call to res_ninit() requires a corresponding call to
106 res_nclose() to free memory allocated by res_ninit() and subsequent
107 calls to res_nquery().
108 The res_nquery() and res_query() functions query the name server for
110 the fully qualified domain name name of specified type and class. The
111 reply is left in the buffer answer of length anslen supplied by the
112 caller.
113 The res_nsearch() and res_search() functions make a query and waits for
115 the response like res_nquery() and res_query(), but in addition they
116 implement the default and search rules controlled by RES_DEFNAMES and
117 RES_DNSRCH (see description of _res options below).
118 The res_nquerydomain() and res_querydomain() functions make a query us‐
120 ing res_nquery()/res_query() on the concatenation of name and domain.
121 The following functions are lower-level routines used by
123 res_nquery()/res_query().
124 The res_nmkquery() and res_mkquery() functions construct a query mes‐
126 sage in buf of length buflen for the domain name dname. The query type
127 op is one of the following (typically QUERY):
128 QUERY Standard query.
130 IQUERY Inverse query. This option was removed in glibc 2.26, since it
132 has not been supported by DNS servers for a very long time.
133 NS_NOTIFY_OP
135 Notify secondary of SOA (Start of Authority) change.
136 newrr is currently unused.
138 The res_nsend() and res_send() function send a preformatted query given
140 in msg of length msglen and returns the answer in answer which is of
141 length anslen. They will call res_ninit()/res_init() if it has not al‐
142 ready been called.
143 The dn_comp() function compresses the domain name exp_dn and stores it
145 in the buffer comp_dn of length length. The compression uses an array
146 of pointers dnptrs to previously compressed names in the current mes‐
147 sage. The first pointer points to the beginning of the message and the
148 list ends with NULL. The limit of the array is specified by lastdnptr.
149 If dnptr is NULL, domain names are not compressed. If lastdnptr is
150 NULL, the list of labels is not updated.
151 The dn_expand() function expands the compressed domain name comp_dn to
153 a full domain name, which is placed in the buffer exp_dn of size
154 length. The compressed name is contained in a query or reply message,
155 and msg points to the beginning of the message.
156 The resolver routines use configuration and state information contained
158 in a __res_state structure (either passed as the statep argument, or in
159 the global variable _res, in the case of the older nonreentrant func‐
160 tions). The only field of this structure that is normally manipulated
161 by the user is the options field. This field can contain the bitwise
162 "OR" of the following options:
163 RES_INIT
165 True if res_ninit() or res_init() has been called.
166 RES_DEBUG
168 Print debugging messages. This option is available only if
169 glibc was built with debugging enabled, which is not the de‐
170 fault.
171 RES_AAONLY (unimplemented; deprecated in glibc 2.25)
173 Accept authoritative answers only. res_send() continues until
174 it finds an authoritative answer or returns an error. This op‐
175 tion was present but unimplemented until glibc 2.24; since glibc
176 2.25, it is deprecated, and its usage produces a warning.
177 RES_USEVC
179 Use TCP connections for queries rather than UDP datagrams.
180 RES_PRIMARY (unimplemented; deprecated in glibc 2.25)
182 Query primary domain name server only. This option was present
183 but unimplemented until glibc 2.24; since glibc 2.25, it is dep‐
184 recated, and its usage produces a warning.
185 RES_IGNTC
187 Ignore truncation errors. Don't retry with TCP.
188 RES_RECURSE
190 Set the recursion desired bit in queries. Recursion is carried
191 out by the domain name server, not by res_send(). [Enabled by
192 default].
193 RES_DEFNAMES
195 If set, res_search() will append the default domain name to sin‐
196 gle component names—that is, those that do not contain a dot.
197 [Enabled by default].
198 RES_STAYOPEN
200 Used with RES_USEVC to keep the TCP connection open between
201 queries.
202 RES_DNSRCH
204 If set, res_search() will search for hostnames in the current
205 domain and in parent domains. This option is used by gethostby‐
206 name(3). [Enabled by default].
207 RES_INSECURE1
209 Accept a response from a wrong server. This can be used to de‐
210 tect potential security hazards, but you need to compile glibc
211 with debugging enabled and use RES_DEBUG option (for debug pur‐
212 pose only).
213 RES_INSECURE2
215 Accept a response which contains a wrong query. This can be
216 used to detect potential security hazards, but you need to com‐
217 pile glibc with debugging enabled and use RES_DEBUG option (for
218 debug purpose only).
219 RES_NOALIASES
221 Disable usage of HOSTALIASES environment variable.
222 RES_USE_INET6
224 Try an AAAA query before an A query inside the gethostbyname(3)
225 function, and map IPv4 responses in IPv6 "tunneled form" if no
226 AAAA records are found but an A record set exists. Since glibc
227 2.25, this option is deprecated, and its usage produces a warn‐
228 ing; applications should use getaddrinfo(3), rather than geth‐
229 ostbyname(3).
230 RES_ROTATE
232 Causes round-robin selection of name servers from among those
233 listed. This has the effect of spreading the query load among
234 all listed servers, rather than having all clients try the first
235 listed server first every time.
236 RES_NOCHECKNAME (unimplemented; deprecated in glibc 2.25)
238 Disable the modern BIND checking of incoming hostnames and mail
239 names for invalid characters such as underscore (_), non-ASCII,
240 or control characters. This option was present until glibc
241 2.24; since glibc 2.25, it is deprecated, and its usage produces
242 a warning.
243 RES_KEEPTSIG (unimplemented; deprecated in glibc 2.25)
245 Do not strip TSIG records. This option was present but unimple‐
246 mented until glibc 2.24; since glibc 2.25, it is deprecated, and
247 its usage produces a warning.
248 RES_BLAST (unimplemented; deprecated in glibc 2.25)
250 Send each query simultaneously and recursively to all servers.
251 This option was present but unimplemented until glibc 2.24;
252 since glibc 2.25, it is deprecated, and its usage produces a
253 warning.
254 RES_USEBSTRING (glibc 2.3.4 to glibc 2.24)
256 Make reverse IPv6 lookups using the bit-label format described
257 in RFC 2673; if this option is not set (which is the default),
258 then nibble format is used. This option was removed in glibc
259 2.25, since it relied on a backward-incompatible DNS extension
260 that was never deployed on the Internet.
261 RES_NOIP6DOTINT (glibc 2.24 and earlier)
263 Use ip6.arpa zone in IPv6 reverse lookup instead of ip6.int,
264 which is deprecated since glibc 2.3.4. This option is present
265 up to and including glibc 2.24, where it is enabled by default.
266 In glibc 2.25, this option was removed.
267 RES_USE_EDNS0 (since glibc 2.6)
269 Enables support for the DNS extensions (EDNS0) described in RFC
270 2671.
271 RES_SNGLKUP (since glibc 2.10)
273 By default, glibc performs IPv4 and IPv6 lookups in parallel
274 since glibc 2.9. Some appliance DNS servers cannot handle these
275 queries properly and make the requests time out. This option
276 disables the behavior and makes glibc perform the IPv6 and IPv4
277 requests sequentially (at the cost of some slowdown of the re‐
278 solving process).
279 RES_SNGLKUPREOP
281 When RES_SNGLKUP option is enabled, opens a new socket for the
282 each request.
283 RES_USE_DNSSEC
285 Use DNSSEC with OK bit in OPT record. This option implies
286 RES_USE_EDNS0.
287 RES_NOTLDQUERY
289 Do not look up unqualified name as a top-level domain (TLD).
290 RES_DEFAULT
292 Default option which implies: RES_RECURSE, RES_DEFNAMES,
293 RES_DNSRCH, and RES_NOIP6DOTINT.
294
296 The res_ninit() and res_init() functions return 0 on success, or -1 if
297 an error occurs.
298 The res_nquery(), res_query(), res_nsearch(), res_search(), res_nquery‐
300 domain(), res_querydomain(), res_nmkquery(), res_mkquery(),
301 res_nsend(), and res_send() functions return the length of the re‐
302 sponse, or -1 if an error occurs.
303 The dn_comp() and dn_expand() functions return the length of the com‐
305 pressed name, or -1 if an error occurs.
306 In the case of an error return from res_nquery(), res_query(),
308 res_nsearch(), res_search(), res_nquerydomain(), or res_querydomain(),
309 the global variable h_errno (see gethostbyname(3)) can be consulted to
310 determine the cause of the error.
311
313 /etc/resolv.conf
314 resolver configuration file
315 /etc/host.conf
317 resolver configuration file
318
320 For an explanation of the terms used in this section, see at‐
321 tributes(7).
322 ┌─────────────────────────────────────┬───────────────┬────────────────┐
324 │Interface │ Attribute │ Value │
325 ├─────────────────────────────────────┼───────────────┼────────────────┤
326 │res_ninit(), res_nclose(), │ Thread safety │ MT-Safe locale │
327 │res_nquery(), res_nsearch(), │ │ │
328 │res_nquerydomain(), res_nsend() │ │ │
329 ├─────────────────────────────────────┼───────────────┼────────────────┤
330 │res_nmkquery(), dn_comp(), │ Thread safety │ MT-Safe │
331 │dn_expand() │ │ │
332 └─────────────────────────────────────┴───────────────┴────────────────┘
333
335 None.
336
338 4.3BSD.
339
341 gethostbyname(3), resolv.conf(5), resolver(5), hostname(7), named(8)
342 The GNU C library source file resolv/README.
344Linux man-pages 6.05 2023-07-20 resolver(3)