3 * - adns user-visible API (single-threaded, without any locking)
6 * This file is part of adns, which is Copyright (C) 1997-1999 Ian Jackson
8 * This program is free software; you can redistribute it and/or modify
9 * it under the terms of the GNU General Public License as published by
10 * the Free Software Foundation; either version 2, or (at your option)
13 * This program is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 * GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with this program; if not, write to the Free Software Foundation,
20 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25 #ifndef ADNS_H_INCLUDED
26 #define ADNS_H_INCLUDED
30 #include <sys/socket.h>
31 #include <netinet/in.h>
33 /* All struct in_addr anywhere in adns are in NETWORK byte order. */
35 typedef struct adns__state
*adns_state
;
36 typedef struct adns__query
*adns_query
;
39 adns_if_noenv
= 0x0001, /* do not look at environment */
40 adns_if_noerrprint
= 0x0002, /* never print output to stderr (_debug overrides) */
41 adns_if_noserverwarn
= 0x0004, /* do not warn to stderr about duff nameservers etc */
42 adns_if_debug
= 0x0008, /* enable all output to stderr plus debug msgs */
43 adns_if_noautosys
= 0x0010, /* do not make syscalls at every opportunity */
44 adns_if_eintr
= 0x0020, /* allow _wait and _synchronous to return EINTR */
46 /* Flags for address formatting, in both init and query. Do not use directly. */
47 adns__iqaf_keepv4
= 0x01000, /* If clear, any IPv4s will be mapped to AF_INET6 */
48 adns__iqaf_weakv6
= 0x02000, /* `Prefer IPv6 less' - depends on other flags */
49 adns__iqaf_only
= 0x04000, /* Return only one kind of address */
50 adns__iqaf_override
= 0x08000, /* In query flags, means to ignore init flags */
51 adns__iqaf_mask
= 0x07000, /* Mask of flags that _override overrides */
53 /* Actual address formatting options. These set the default. Do not combine them.
55 * _v6first: Query for AAAA; if no AAAA then query for A. Return all as AF_INET6.
56 * _v6first: Same, but return IPv6 as AF_INET6 and IPv4 as AF_INET.
57 * _both: Query for both A and AAAA, return all addresses as AF_INET6.
58 * _bothraw: Same, but return IPv6 as AF_INET6 and IPv4 as AF_INET.
59 * _v4only: Query only for A, and return as AF_INET.
60 * _v6only: Query only for AAAA, and return as AF_INET6.
61 * If none is specified, the default is _v6first.
63 adns_if_addr_v6first
= 0,
64 adns_if_addr_v6firstraw
= adns__iqaf_keepv4
,
65 adns_if_addr_both
= adns__iqaf_weakv6
,
66 adns_if_addr_bothraw
= adns__iqaf_weakv6
|adns__iqaf_keepv4
,
67 adns_if_addr_v4only
= adns__iqaf_only
|adns__iqaf_weakv6
|adns__iqaf_keepv4
,
68 adns_if_addr_v6only
= adns__iqaf_only
,
70 adns__if_internalmask
= 0x7fff0000
74 adns_qf_search
= 0x0000001, /* use the searchlist */
75 adns_qf_usevc
= 0x0000002, /* use a virtual circuit (TCP connection) */
76 adns_qf_quoteok_query
= 0x0000010, /* allow quote-requiring chars in query domain */
77 adns_qf_quoteok_cname
= 0x0000020, /* allow ... in CNAME we go via */
78 adns_qf_quoteok_anshost
= 0x0000040, /* allow ... in answers expected to be hostnames */
79 adns_qf_cname_loose
= 0x0000100, /* allow refs to CNAMEs - without, get _s_cname */
80 adns_qf_cname_forbid
= 0x0000200, /* don't follow CNAMEs, instead give _s_cname */
82 /* Address formatting options. They have the same meaning as the corresponding
83 * adns_if_... options. Do not combine with other _if_addr/_qf_addr options.
84 * If a _qf_addr is specified then the _if_addr are irrelevant, otherwise the
87 adns_qf_addr_both
= adns__iqaf_override
|adns_if_addr_both
,
88 adns_qf_addr_bothraw
= adns__iqaf_override
|adns_if_addr_bothraw
,
89 adns_qf_addr_v6first
= adns__iqaf_override
|adns_if_addr_v6first
,
90 adns_qf_addr_v6firstraw
= adns__iqaf_override
|adns_if_addr_v6firstraw
,
91 adns_qf_addr_v4only
= adns__iqaf_override
|adns_if_addr_v4only
,
92 adns_qf_addr_v6only
= adns__iqaf_override
|adns_if_addr_v6only
,
94 adns__qf_internalmask
= 0x7fff0000
98 adns__rrt_typemask
= 0x0ffff,
99 adns__qtf_deref
= 0x10000, /* dereference domains and perhaps produce extra data */
100 adns__qtf_mail822
= 0x20000, /* make mailboxes be in RFC822 rcpt field format */
101 adns__qtf_nostdquery
= 0x40000, /* do not make normal initial query */
102 adns__qtf_mask
= 0x07fff0000,
109 adns_r_ns
= adns_r_ns_raw
|adns__qtf_deref
,
114 adns_r_soa
= adns_r_soa_raw
|adns__qtf_mail822
,
117 adns_r_ptr
= adns_r_ptr_raw
|adns__qtf_deref
,
122 adns_r_mx
= adns_r_mx_raw
|adns__qtf_deref
,
127 adns_r_rp
= adns_r_rp_raw
|adns__qtf_mail822
,
131 adns_r_addr
= adns_r_a
|adns__qtf_nostdquery
135 /* In queries without qtf_anyquote, all domains must have standard
136 * legal syntax. In queries _with_ qtf_anyquote, domains in the query
137 * or response may contain any characters, quoted according to
138 * RFC1035 5.1. On input to adns, the char* is a pointer to the
139 * interior of a " delimited string, except that " may appear in it,
140 * and on output, the char* is a pointer to a string which would be
141 * legal either inside or outside " delimiters, and any characters
142 * not usually legal in domain names will be quoted as \X
143 * (if the character is 33-126 except \ and ") or \DDD.
145 * Do not ask for _raw records containing mailboxes without
146 * specifying _qf_anyquote.
152 /* locally induced errors */
154 adns_s_unknownrrtype
,
156 /* remotely induced errors, detected locally */
160 adns_s_invalidresponse
,
161 adns_s_unknownformat
,
163 /* remotely induced errors, reported by remote server to us */
164 adns_s_rcodeservfail
,
165 adns_s_rcodeformaterror
,
166 adns_s_rcodenotimplemented
,
170 adns_s_max_tempfail
= 99,
172 /* remote configuration errors */
173 adns_s_inconsistent
, /* PTR gives domain whose A does not exist and match */
174 adns_s_prohibitedcname
, /* CNAME found where eg A expected (not if _qf_loosecname) */
175 adns_s_answerdomaininvalid
,
176 adns_s_answerdomaintoolong
,
179 adns_s_max_misconfig
= 199,
181 /* permanent problems with the query */
182 adns_s_querydomainwrong
,
183 adns_s_querydomaininvalid
,
184 adns_s_querydomaintoolong
,
186 adns_s_max_misquery
= 299,
188 /* permanent errors */
198 struct sockaddr_in inet
; /* port field will be zero */
199 struct sockaddr_in6 inet6
; /* port field will be zero */
206 int naddrs
; /* temp fail => -1, perm fail => 0, s_ok => >0 */
217 } adns_rr_inthostaddr
;
220 /* Used both for mx_raw, in which case i is the preference and str the domain,
221 * and for txt, in which case each entry has i for the `text' length,
222 * and str for the data (which will have had an extra nul appended
223 * so that if it was plain text it is now a null-terminated string).
230 adns_rr_intstr array
[2];
231 } adns_rr_intstrpair
;
235 unsigned long serial
, refresh
, retry
, expire
, minimum
;
240 char *cname
; /* always NULL if query was for CNAME records */
241 adns_rrtype type
; /* guaranteed to be same as in query */
245 unsigned char *bytes
;
246 char *(*str
); /* ns_raw, cname, ptr, ptr_raw */
247 adns_rr_intstr
*(*manyistr
); /* txt (list of strings ends with i=-1, str=0) */
248 adns_rr_addr
*addr
; /* addr */
249 struct in_addr
*inaddr
; /* a */
250 struct in_addr6
*inaddr6
; /* aaaa */
251 adns_rr_hostaddr
*hostaddr
; /* ns */
252 adns_rr_intstrpair
*intstrpair
; /* hinfo */
253 adns_rr_strpair
*strpair
; /* rp, rp_raw */
254 adns_rr_inthostaddr
*inthostaddr
; /* mx */
255 adns_rr_intstr
*intstr
; /* mx_raw */
256 adns_rr_soa
*soa
; /* soa, soa_raw */
260 /* Memory management:
261 * adns_state and adns_query are actually pointers to malloc'd state;
262 * On submission questions are copied, including the owner domain;
263 * Answers are malloc'd as a single piece of memory; pointers in the
264 * answer struct point into further memory in the answer.
266 * Must always be non-null pointer;
267 * If *query_io is 0 to start with then any query may be returned;
268 * If *query_io is !0 adns_query then only that query may be returned.
269 * If the call is successful, *query_io, *answer_r, and *context_r
272 * Return values are 0 or an errno value;
273 * Seriously fatal system errors (eg, failure to create sockets,
274 * malloc failure, etc.) return errno values;
275 * Other errors (nameserver failure, timed out connections, &c)
276 * are returned in the status field of the answer. If status is
277 * nonzero then nrrs will be 0, otherwise it will be >0.
278 * type will always be the type requested;
279 * If no (appropriate) requests are done adns_check returns EWOULDBLOCK;
280 * If no (appropriate) requests are outstanding adns_query and adns_wait return ESRCH;
283 int adns_init(adns_state
*newstate_r
, adns_initflags flags
,
284 FILE *diagfile
/*0=>stderr*/);
286 int adns_init_strcfg(adns_state
*newstate_r
, adns_initflags flags
,
287 FILE *diagfile
/*0=>discard*/, const char *configtext
);
289 int adns_synchronous(adns_state ads
,
292 adns_queryflags flags
,
293 adns_answer
**answer_r
);
295 /* NB: if you set adns_if_noautosys then _submit and _check do not
296 * make any system calls; you must use adns_callback (possibly after
297 * adns_interest) to actually get things to happen.
300 int adns_submit(adns_state ads
,
303 adns_queryflags flags
,
305 adns_query
*query_r
);
307 int adns_check(adns_state ads
,
308 adns_query
*query_io
,
309 adns_answer
**answer_r
,
312 int adns_wait(adns_state ads
,
313 adns_query
*query_io
,
314 adns_answer
**answer_r
,
316 /* fixme: include TTL in answer somehow */
317 /* fixme: easy way to get lists of fd's */
320 void adns_cancel(adns_query query
);
322 void adns_finish(adns_state
);
323 /* You may call this even if you have queries outstanding;
324 * they will be cancelled.
327 int adns_callback(adns_state
, int maxfd
, const fd_set
*readfds
, const fd_set
*writefds
,
328 const fd_set
*exceptfds
);
329 /* Gives adns flow-of-control for a bit. This will never block.
330 * If maxfd == -1 then adns will check (make nonblocking system calls on)
331 * all of its own filedescriptors; otherwise it will only use those
332 * < maxfd and specified in the fd_set's, as if select had returned them.
333 * Other fd's may be in the fd_sets, and will be ignored.
334 * _callback returns how many adns fd's were in the various sets, so
335 * you can tell if your select handling code has missed something and is going awol.
337 * May also return -1 if a critical syscall failed, setting errno.
340 void adns_interest(adns_state
, int *maxfd_io
, fd_set
*readfds_io
,
341 fd_set
*writefds_io
, fd_set
*exceptfds_io
,
342 struct timeval
**tv_mod
, struct timeval
*tv_buf
);
343 /* Find out file descriptors adns is interested in, and when it
344 * would like the opportunity to time something out. If you do not plan to
345 * block then tv_mod may be 0. Otherwise, tv_mod may point to 0 meaning
346 * you have no timeout of your own, in which case tv_buf must be non-null and
347 * _interest may fill it in and set *tv_mod=tv_buf.
348 * readfds, writefds, exceptfds and maxfd may not be 0.
351 /* Example expected/legal calling sequences:
357 * adns_check 3 -> EWOULDBLOCK
363 * adns_init _noautosys
369 * adns_submit / adns_check
374 adns_status
adns_rr_info(adns_rrtype type
,
375 const char **rrtname_r
, const char **fmtname_r
,
377 const void *datap
, char **data_r
);
378 /* Gets information in human-readable (but non-i18n) form
379 * for eg debugging purposes. type must be specified,
380 * and the official name of the corresponding RR type will
381 * be returned in *rrtname_r, and information about the processing
382 * style in *fmtname_r. The length of the table entry in an answer
383 * for that type will be returned in in *len_r.
384 * Any or all of rrtname_r, fmtname_r and len_r may be 0.
385 * If fmtname_r is non-null then *fmtname_r may be
386 * null on return, indicating that no special processing is
389 * data_r be must be non-null iff datap is. In this case
390 * *data_r will be set to point to a human-readable text
391 * string representing the RR data. The text will have
392 * been obtained from malloc() and must be freed by the caller.
394 * Usually this routine will succeed. Possible errors include:
396 * adns_s_rrtypeunknown
397 * adns_s_invaliddata (*datap contained garbage)
398 * If an error occurs then no memory has been allocated,
399 * and *rrtname_r, *fmtname_r, *len_r and *data_r are undefined.
402 const char *adns_strerror(adns_status st
);