1RESOLVER(3) BSD Library Functions Manual RESOLVER(3)
2
4 res_ninit, res_ourserver_p, fp_resstat, res_hostalias, res_pquery,
5 res_nquery, res_nsearch, res_nquerydomain, res_nmkquery, res_nsend,
6 res_nupdate, res_nmkupdate, res_nclose, res_nsendsigned, res_findzonecut,
7 res_getservers, res_setservers, res_ndestroy, dn_comp, dn_expand,
8 hstrerror, res_init, res_isourserver, fp_nquery, p_query, hostalias,
9 res_query, res_search, res_querydomain, res_mkquery, res_send,
10 res_update, res_close, herror — resolver routines
11
13 #include <sys/types.h>
14 #include <netinet/in.h>
15 #include <arpa/nameser.h>
16 #include <resolv.h>
17 #include <res_update.h>
18 typedef struct __res_state *res_state;
20 int
22 res_ninit(res_state statp);
23 int
25 res_ourserver_p(const res_state statp, const struct sockaddr_in *addr);
26 void
28 fp_resstat(const res_state statp, FILE *fp);
29 const char *
31 res_hostalias(const res_state statp, const char *name, char *buf,
32 size_t buflen);
33 int
35 res_pquery(const res_state statp, const u_char *msg, int msglen,
36 FILE *fp);
37 int
39 res_nquery(res_state statp, const char *dname, int class, int type,
40 u_char *answer, int anslen);
41 int
43 res_nsearch(res_state statp, const char *dname, int class, int type,
44 u_char * answer, int anslen);
45 int
47 res_nquerydomain(res_state statp, const char *name, const char *domain,
48 int class, int type, u_char *answer, int anslen);
49 int
51 res_nmkquery(res_state statp, int op, const char *dname, int class,
52 int type, const u_char *data, int datalen, const u_char *newrr,
53 u_char *buf, int buflen);
54 int
56 res_nsend(res_state statp, const u_char *msg, int msglen, u_char *answer,
57 int anslen);
58 int
60 res_nupdate(res_state statp, ns_updrec *rrecp_in);
61 int
63 res_nmkupdate(res_state statp, ns_updrec *rrecp_in, u_char *buf,
64 int buflen);
65 void
67 res_nclose(res_state statp);
68 int
70 res_nsendsigned(res_state statp, const u_char *msg, int msglen,
71 ns_tsig_key *key, u_char *answer, int anslen);
72 int
74 res_findzonecut(res_state statp, const char *dname, ns_class class,
75 int options, char *zname, size_t zsize, struct in_addr *addrs,
76 int naddrs);
77 int
79 res_getservers(res_state statp, union res_sockaddr_union *set, int cnt);
80 void
82 res_setservers(res_state statp, const union res_sockaddr_union *set,
83 int cnt);
84 void
86 res_ndestroy(res_state statp);
87 int
89 dn_comp(const char *exp_dn, u_char *comp_dn, int length, u_char **dnptrs,
90 u_char **lastdnptr);
91 int
93 dn_expand(const u_char *msg, const u_char *eomorig,
94 const u_char *comp_dn, char *exp_dn, int length);
95 const char *
97 hstrerror(int err);
98 DEPRECATED
100 #include <sys/types.h>
101 #include <netinet/in.h>
102 #include <arpa/nameser.h>
103 #include <resolv.h>
104 #include <res_update.h>
105 int
107 res_init(void);
108 int
110 res_isourserver(const struct sockaddr_in *addr);
111 int
113 fp_nquery(const u_char *msg, int msglen, FILE *fp);
114 void
116 p_query(const u_char *msg, FILE *fp);
117 const char *
119 hostalias(const char *name);
120 int
122 res_query(const char *dname, int class, int type, u_char *answer,
123 int anslen);
124 int
126 res_search(const char *dname, int class, int type, u_char *answer,
127 int anslen);
128 int
130 res_querydomain(const char *name, const char *domain, int class,
131 int type, u_char *answer, int anslen);
132 int
134 res_mkquery(int op, const char *dname, int class, int type,
135 const char *data, int datalen, struct rrec *newrr, u_char *buf,
136 int buflen);
137 int
139 res_send(const u_char *msg, int msglen, u_char *answer, int anslen);
140 int
142 res_update(ns_updrec *rrecp_in);
143 void
145 res_close(void);
146 void
148 herror(const char *s);
149
151 These routines are used for making, sending and interpreting query and
152 reply messages with Internet domain name servers.
153 State information is kept in statp and is used to control the behavior of
155 these functions. statp should be set to all zeros prior to the first
156 call to any of these functions.
157 The functions res_init(), res_isourserver(), fp_nquery(), p_query(),
159 hostalias(), res_query(), res_search(), res_querydomain(), res_mkquery(),
160 res_send(), res_update(), res_close() and herror() are deprecated and are
161 supplied for compatability with old source code. They use global config‐
162 uration and state information that is kept in the structure _res rather
163 than that referenced through statp.
164 Most of the values in statp and _res are initialized on the first call to
166 res_ninit() / res_init() to reasonable defaults and can be ignored.
167 Options stored in statp->options / _res.options are defined in resolv.h
168 and are as follows. Options are stored as a simple bit mask containing
169 the bitwise “OR” of the options enabled.
170 RES_INIT
172 True if the initial name server address and default domain name
173 are initialized (i.e., res_ninit() / res_init() has been
174 called).
175 RES_DEBUG
177 Print debugging messages.
178 RES_AAONLY
180 Accept authoritative answers only. Should continue until it
181 finds an authoritative answer or finds an error. Currently this
182 is not implemented.
183 RES_USEVC
185 Use TCP connections for queries instead of UDP datagrams.
186 RES_STAYOPEN
188 Used with RES_USEVC to keep the TCP connection open between
189 queries. This is useful only in programs that regularly do many
190 queries. UDP should be the normal mode used.
191 RES_IGNTC
193 Ignore truncation errors, i.e., don't retry with TCP.
194 RES_RECURSE
196 Set the recursion-desired bit in queries. This is the default.
197 (res_nsend() / res_send() does not do iterative queries and
198 expects the name server to handle recursion.)
199 RES_DEFNAMES
201 If set, res_nsearch() / res_search() will append the default
202 domain name to single-component names (those that do not contain
203 a dot). This option is enabled by default.
204 RES_DNSRCH
206 If this option is set, res_nsearch() / res_search() will search
207 for host names in the current domain and in parent domains; see
208 hostname(7). This is used by the standard host lookup routine
209 gethostbyname(3). This option is enabled by default.
210 RES_NOALIASES
212 This option turns off the user level aliasing feature controlled
213 by the HOSTALIASES environment variable. Network daemons should
214 set this option.
215 RES_USE_INET6
217 This option causes gethostbyname(3) to look for AAAA records
218 before looking for A records if none are found.
219 RES_ROTATE
221 This options causes the res_nsend() / res_send() to rotate the
222 list of nameservers in statp->nsaddr_list / _res.nsaddr_list.
223 RES_KEEPTSIG
225 This option causes res_nsendsigned() to leave the message
226 unchanged after TSIG verification; otherwise the TSIG record
227 would be removed and the header updated.
228 RES_NOTLDQUERY
230 This option causes res_nsearch() to not attempt to resolve a
231 unqualified name as if it were a top level domain (TLD). This
232 option can cause problems if the site has "localhost" as a TLD
233 rather than having localhost on one or more elements of the
234 search list. This option has no effect if neither RES_DEFNAMES
235 or RES_DNSRCH is set.
236 The res_ninit() / res_init() routine reads the configuration file (if
238 any; see resolver(5)) to get the default domain name, search list and the
239 Internet address of the local name server(s). If no server is config‐
240 ured, the host running the resolver is tried. The current domain name is
241 defined by the hostname if not specified in the configuration file; it
242 can be overridden by the environment variable LOCALDOMAIN. This environ‐
243 ment variable may contain several blank-separated tokens if you wish to
244 override the “search list” on a per-process basis. This is similar to
245 the search command in the configuration file. Another environment vari‐
246 able (“RES_OPTIONS”) can be set to override certain internal resolver
247 options which are otherwise set by changing fields in the statp / _res
248 structure or are inherited from the configuration file's options command.
249 The syntax of the “RES_OPTIONS” environment variable is explained in
250 resolver(5). Initialization normally occurs on the first call to one of
251 the other resolver routines.
252 The memory referred to by statp must be set to all zeros prior to the
254 first call to res_ninit(). res_ndestroy() should be call to free memory
255 allocated by res_ninit() after last use.
256 The res_nquery() / res_query() functions provides interfaces to the
258 server query mechanism. They constructs a query, sends it to the local
259 server, awaits a response, and makes preliminary checks on the reply.
260 The query requests information of the specified type and class for the
261 specified fully-qualified domain name dname. The reply message is left
262 in the answer buffer with length anslen supplied by the caller.
263 res_nquery() / res_query() return -1 on error or the length of the
264 answer.
265 The res_nsearch() / res_search() routines make a query and awaits a
267 response like res_nquery() / res_query(), but in addition, it implements
268 the default and search rules controlled by the RES_DEFNAMES and
269 RES_DNSRCH options. It returns the length of the first successful reply
270 which is stored in answer or -1 on error.
271 The remaining routines are lower-level routines used by res_nquery() /
273 res_query(). The res_nmkquery() / res_mkquery() functions constructs a
274 standard query message and places it in buf. It returns the size of the
275 query, or -1 if the query is larger than buflen. The query type op is
276 usually QUERY, but can be any of the query types defined in
277 <arpa/nameser.h>. The domain name for the query is given by dname.
278 Newrr is currently unused but is intended for making update messages.
279 The res_nsend() / res_send() / res_nsendsigned() routines sends a pre-
281 formatted query and returns an answer. It will call res_ninit() /
282 res_init() if RES_INIT is not set, send the query to the local name
283 server, and handle timeouts and retries. Additionally, res_nsendsigned()
284 will use TSIG signatures to add authentication to the query and verify
285 the response. In this case, only one nameserver will be contacted. The
286 length of the reply message is returned, or -1 if there were errors.
287 res_nquery() / res_query(), res_nsearch() / res_search() and res_nsend()
289 / res_send() return a length that may be bigger than anslen. In that
290 case the query should be retried with a bigger buffer. NOTE the answer
291 to the second query may be larger still so supplying a buffer that bigger
292 that the answer returned by the previous query is recommended.
293 answer MUST be big enough to receive a maximum UDP response from the
295 server or parts of the answer will be silently discarded. The default
296 maximum UDP response size is 512 bytes.
297 The function res_ourserver_p() returns true when inp is one of the
299 servers in statp->nsaddr_list / _res.nsaddr_list.
300 The functions fp_nquery() / p_query() print out the query and any answer
302 in msg on fp. p_query() is equivalent to fp_nquery() with msglen set to
303 512.
304 The function fp_resstat() prints out the active flag bits in
306 statp->options preceeded by the text ";; res options:" on file.
307 The functions res_hostalias() / hostalias() lookup up name in the file
309 referred to by the HOSTALIASES files return a fully qualified hostname if
310 found or NULL if not found or an error occurred. res_hostalias() uses
311 buf to store the result in, hostalias() uses a static buffer.
312 The functions res_getservers() and res_setservers() are used to get and
314 set the list of server to be queried.
315 The functions res_nupdate() / res_update() take a list of ns_updrec
317 rrecp_in. Identifies the containing zone for each record and groups the
318 records according to containing zone maintaining in zone order then sends
319 and update request to the servers for these zones. The number of zones
320 updated is returned or -1 on error. Note that res_nupdate() will perform
321 TSIG authenticated dynamic update operations if the key is not NULL.
322 The function res_findzonecut() discovers the closest enclosing zone cut
324 for a specified domain name, and finds the IP addresses of the zone's
325 master servers.
326 The functions res_nmkupdate() / res_mkupdate() take a linked list of
328 ns_updrec rrecp_in and construct a UPDATE message in buf.
329 res_nmkupdate() / res_mkupdate() return the length of the constructed
330 message on no error or one of the following error values.
331 -1 An error occurred parsing rrecp_in.
333 -2 The buffer buf was too small.
335 -3 The first record was not a zone section or there was a section order
337 problem. The section order is S_ZONE, S_PREREQ and S_UPDATE.
338 -4 A number overflow occurred.
340 -5 Unknown operation or no records.
342 The functions res_nclose() / res_close() close any open files referenced
344 through statp / _res.
345 The function res_ndestroy() calls res_nclose() then frees any memory
347 allocated by res_ninit().
348 The dn_comp() function compresses the domain name exp_dn and stores it in
350 comp_dn. The size of the compressed name is returned or -1 if there were
351 errors. The size of the array pointed to by comp_dn is given by length.
352 The compression uses an array of pointers dnptrs to previously-compressed
353 names in the current message. The first pointer points to to the begin‐
354 ning of the message and the list ends with NULL. The limit to the array
355 is specified by lastdnptr. A side effect of dn_comp() is to update the
356 list of pointers for labels inserted into the message as the name is com‐
357 pressed. If dnptr is NULL, names are not compressed. If lastdnptr is
358 NULL, the list of labels is not updated.
359 The dn_expand() entry expands the compressed domain name comp_dn to a
361 full domain name. The compressed name is contained in a query or reply
362 message; msg is a pointer to the beginning of the message. eomorig is a
363 pointer to the first location after the message. The uncompressed name
364 is placed in the buffer indicated by exp_dn which is of size length. The
365 size of compressed name is returned or -1 if there was an error.
366 The variables statp->res_h_errno / _res.res_h_errno and external variable
368 h_errno is set whenever an error occurs during resolver operation. The
369 following definitions are given in <netdb.h>:
370 #define NETDB_INTERNAL -1 /* see errno */
372 #define NETDB_SUCCESS 0 /* no problem */
373 #define HOST_NOT_FOUND 1 /* Authoritative Answer Host not found */
374 #define TRY_AGAIN 2 /* Non-Authoritative not found, or SERVFAIL */
375 #define NO_RECOVERY 3 /* Non-Recoverable: FORMERR, REFUSED, NOTIMP */
376 #define NO_DATA 4 /* Valid name, no data for requested type */
377 The herror() function writes a message to the diagnostic output consist‐
379 ing of the string parameter s, the constant string ": ", and a message
380 corresponding to the value of h_errno.
381 The hstrerror() function returns a string which is the message text cor‐
383 responding to the value of the err parameter.
384
386 /etc/resolv.conf See resolver(5).
387
389 gethostbyname(3), hostname(7), resolver(5); RFC1032, RFC1033, RFC1034,
390 RFC1035, RFC974; SMM:11, “Name Server Operations Guide for BIND”
3914th Berkeley Distribution July 4, 2000 4th Berkeley Distribution