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