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 */
45 adns_if_nosigpipe
= 0x0040, /* applic has SIGPIPE set to SIG_IGN, do not protect */
49 adns_qf_search
= 0x000001, /* use the searchlist */
50 adns_qf_usevc
= 0x000002, /* use a virtual circuit (TCP connection) */
51 adns_qf_owner
= 0x000004, /* fill in the owner field in the answer */
52 adns_qf_quoteok_query
= 0x000010, /* allow quote-requiring chars in query domain */
53 adns_qf_quoteok_cname
= 0x000020, /* allow ... in CNAME we go via */
54 adns_qf_quoteok_anshost
= 0x000040, /* allow ... in answers expected to be hostnames */
55 adns_qf_cname_loose
= 0x000100, /* allow refs to CNAMEs - without, get _s_cname */
56 adns_qf_cname_forbid
= 0x000200, /* don't follow CNAMEs, instead give _s_cname */
57 adns__qf_internalmask
= 0x0ff000
61 adns__rrt_typemask
= 0x0ffff,
62 adns__qtf_deref
= 0x10000, /* dereference domains and perhaps produce extra data */
63 adns__qtf_mail822
= 0x20000, /* make mailboxes be in RFC822 rcpt field format */
70 adns_r_ns
= adns_r_ns_raw
|adns__qtf_deref
,
75 adns_r_soa
= adns_r_soa_raw
|adns__qtf_mail822
,
78 adns_r_ptr
= adns_r_ptr_raw
|adns__qtf_deref
,
83 adns_r_mx
= adns_r_mx_raw
|adns__qtf_deref
,
88 adns_r_rp
= adns_r_rp_raw
|adns__qtf_mail822
,
90 adns_r_addr
= adns_r_a
|adns__qtf_deref
94 /* In queries without qf_quoteok_*, all domains must have standard
95 * legal syntax. In queries _with_ qf_quoteok_*, domains in the query
96 * or response may contain any characters, quoted according to RFC1035
97 * 5.1. On input to adns, the char* is a pointer to the interior of a
98 * " delimited string, except that " may appear in it, and on output,
99 * the char* is a pointer to a string which would be legal either
100 * inside or outside " delimiters, and any characters not usually
101 * legal in domain names will be quoted as \X (if the character is
102 * 33-126 except \ and ") or \DDD.
104 * Do not ask for _raw records containing mailboxes without
105 * specifying _qf_anyquote.
111 /* locally induced errors */
113 adns_s_unknownrrtype
,
116 adns_s_max_localfail
= 29,
118 /* remotely induced errors, detected locally */
122 adns_s_invalidresponse
,
123 adns_s_unknownformat
,
125 adns_s_max_remotefail
= 59,
127 /* remotely induced errors, reported by remote server to us */
128 adns_s_rcodeservfail
,
129 adns_s_rcodeformaterror
,
130 adns_s_rcodenotimplemented
,
134 adns_s_max_tempfail
= 99,
136 /* remote configuration errors */
137 adns_s_inconsistent
, /* PTR gives domain whose A does not exist and match */
138 adns_s_prohibitedcname
, /* CNAME found where eg A expected (not if _qf_loosecname) */
139 adns_s_answerdomaininvalid
,
140 adns_s_answerdomaintoolong
,
143 adns_s_max_misconfig
= 199,
145 /* permanent problems with the query */
146 adns_s_querydomainwrong
,
147 adns_s_querydomaininvalid
,
148 adns_s_querydomaintoolong
,
150 adns_s_max_misquery
= 299,
152 /* permanent errors */
162 struct sockaddr_in inet
;
169 int naddrs
; /* temp fail => -1, perm fail => 0, s_ok => >0 */
180 } adns_rr_inthostaddr
;
183 /* Used both for mx_raw, in which case i is the preference and str the domain,
184 * and for txt, in which case each entry has i for the `text' length,
185 * and str for the data (which will have had an extra nul appended
186 * so that if it was plain text it is now a null-terminated string).
193 adns_rr_intstr array
[2];
194 } adns_rr_intstrpair
;
198 unsigned long serial
, refresh
, retry
, expire
, minimum
;
203 char *cname
; /* always NULL if query was for CNAME records */
204 char *owner
; /* only set if requested in query flags */
205 adns_rrtype type
; /* guaranteed to be same as in query */
206 time_t expires
; /* expiry time, defined only if _s_ok, nxdomain or nodata. NOT TTL! */
210 unsigned char *bytes
;
211 char *(*str
); /* ns_raw, cname, ptr, ptr_raw */
212 adns_rr_intstr
*(*manyistr
); /* txt (list of strings ends with i=-1, str=0) */
213 adns_rr_addr
*addr
; /* addr */
214 struct in_addr
*inaddr
; /* a */
215 adns_rr_hostaddr
*hostaddr
; /* ns */
216 adns_rr_intstrpair
*intstrpair
; /* hinfo */
217 adns_rr_strpair
*strpair
; /* rp, rp_raw */
218 adns_rr_inthostaddr
*inthostaddr
; /* mx */
219 adns_rr_intstr
*intstr
; /* mx_raw */
220 adns_rr_soa
*soa
; /* soa, soa_raw */
224 /* Memory management:
225 * adns_state and adns_query are actually pointers to malloc'd state;
226 * On submission questions are copied, including the owner domain;
227 * Answers are malloc'd as a single piece of memory; pointers in the
228 * answer struct point into further memory in the answer.
230 * Must always be non-null pointer;
231 * If *query_io is 0 to start with then any query may be returned;
232 * If *query_io is !0 adns_query then only that query may be returned.
233 * If the call is successful, *query_io, *answer_r, and *context_r
236 * Return values are 0 or an errno value.
238 * For _init, _init_strcfg, _submit and _synchronous, system errors
239 * (eg, failure to create sockets, malloc failure, etc.) return errno
242 * For _wait and _check failures are reported in the answer
243 * structure, and only 0, ESRCH or (for _check) EWOULDBLOCK is
244 * returned: if no (appropriate) requests are done adns_check returns
245 * EWOULDBLOCK; if no (appropriate) requests are outstanding both
246 * adns_query and adns_wait return ESRCH.
248 * Additionally, _wait can return EINTR if you set adns_if_eintr.
250 * All other errors (nameserver failure, timed out connections, &c)
251 * are returned in the status field of the answer. After a
252 * successful _wait or _check, if status is nonzero then nrrs will be
253 * 0, otherwise it will be >0. type will always be the type
257 int adns_init(adns_state
*newstate_r
, adns_initflags flags
,
258 FILE *diagfile
/*0=>stderr*/);
260 int adns_init_strcfg(adns_state
*newstate_r
, adns_initflags flags
,
261 FILE *diagfile
/*0=>discard*/, const char *configtext
);
263 int adns_synchronous(adns_state ads
,
266 adns_queryflags flags
,
267 adns_answer
**answer_r
);
269 /* NB: if you set adns_if_noautosys then _submit and _check do not
270 * make any system calls; you must use some of the asynch-io event
271 * processing functions to actually get things to happen.
274 int adns_submit(adns_state ads
,
277 adns_queryflags flags
,
279 adns_query
*query_r
);
281 int adns_check(adns_state ads
,
282 adns_query
*query_io
,
283 adns_answer
**answer_r
,
286 int adns_wait(adns_state ads
,
287 adns_query
*query_io
,
288 adns_answer
**answer_r
,
291 void adns_cancel(adns_query query
);
293 /* The adns_query you get back from _submit is valid (ie, can be
294 * legitimately passed into adns functions) until it is returned by
295 * adns_check or adns_wait, or passed to adns_cancel. After that it
296 * must not be used. You can rely on it not being reused until the
297 * first adns_submit or _transact call using the same adns_state after
298 * it became invalid, so you may compare it for equality with other
299 * query handles until you next call _query or _transact.
302 void adns_finish(adns_state ads
);
303 /* You may call this even if you have queries outstanding;
304 * they will be cancelled.
308 struct adns_query
adns_forallqueries_begin(adns_state ads
, void **context_r
);
309 struct adns_query
adns_forallqueries_next(adns_state ads
, adns_query
, void **context_r
);
310 /* Iterator functions, which you can use to loop over the outstanding
311 * (submitted but not yet successfuly checked/waited) queries. Each
312 * function returns a query handle and a corresponding context pointer,
313 * or returns 0 setting *context_r to 0 if there are no (more) queries.
314 * There is no need to explicitly finish an iteration. context_r may be 0.
316 * IMPORTANT: you MUST NOT call ANY other adns function with the same
317 * adns_state, or with a query in the same adns_state, while you are
318 * doing one of these iterations. After such a call the iterator
319 * value has undefined meaning and must not be used.
323 * Example expected/legal calling sequence for submit/check/wait:
329 * adns_check 3 -> EWOULDBLOCK
337 * Entrypoints for generic asynch io:
338 * (these entrypoints are not very useful except in combination with *
339 * some of the other I/O model calls which can tell you which fds to
342 * Note that any adns call may cause adns to open and close fds, so
343 * you must call beforeselect or beforepoll again just before
344 * blocking, or you may not have an up-to-date list of it's fds.
347 int adns_processany(adns_state ads
);
348 /* Gives adns flow-of-control for a bit. This will never block, and
349 * can be used with any threading/asynch-io model. If some error
350 * occurred which might cause an event loop to spin then the errno
354 int adns_processreadable(adns_state ads
, int fd
, const struct timeval
*now
);
355 int adns_processwriteable(adns_state ads
, int fd
, const struct timeval
*now
);
356 int adns_processexceptional(adns_state ads
, int fd
, const struct timeval
*now
);
357 /* Gives adns flow-of-control so that it can process incoming data
358 * from, or send outgoing data via, fd. Very like _processany. If it
359 * returns zero then fd will no longer be readable or writeable
360 * (unless of course more data has arrived since). adns will _only_
361 * that fd and only in the manner specified, regardless of whether
362 * adns_if_noautosys was specified.
364 * adns_processexceptional should be called when select(2) reports an
365 * exceptional condition, or poll(2) reports POLLPRI.
367 * It is fine to call _processreabable or _processwriteable when the
368 * fd is not ready, or with an fd that doesn't belong to adns; it will
369 * then just return 0.
371 * If some error occurred which might prevent an event loop to spin
372 * then the errno value is returned.
375 void adns_processtimeouts(adns_state ads
, const struct timeval
*now
);
376 /* Gives adns flow-of-control so that it can process any timeouts
377 * which might have happened. Very like _processreadable/writeable.
379 * now may be 0; if it isn't, *now must be the current time, recently
380 * obtained from gettimeofday.
383 void adns_firsttimeout(adns_state ads
,
384 struct timeval
**tv_mod
, struct timeval
*tv_buf
,
386 /* Asks adns when it would first like the opportunity to time
387 * something out. now must be the current time, from gettimeofday.
389 * If tv_mod points to 0 then tv_buf must be non-null, and
390 * _firsttimeout will fill in *tv_buf with the time until the first
391 * timeout, and make *tv_mod point to tv_buf. If adns doesn't have
392 * anything that might need timing out it will leave *tv_mod as 0.
394 * If *tv_mod is not 0 then tv_buf is not used. adns will update
395 * *tv_mod if it has any earlier timeout, and leave it alone if it
398 * This call will not actually do any I/O, or change the fds that adns
399 * is using. It always succeeds and never blocks.
402 void adns_globalsystemfailure(adns_state ads
);
403 /* If serious problem(s) happen which globally affect your ability to
404 * interact properly with adns, or adns's ability to function
405 * properly, you or adns can call this function.
407 * All currently outstanding queries will be made to fail with
408 * adns_s_systemfail, and adns will close any stream sockets it has
411 * This is used by adns, for example, if gettimeofday() fails.
412 * Without this the program's event loop might start to spin !
414 * This call will never block.
418 * Entrypoints for select-loop based asynch io:
421 void adns_beforeselect(adns_state ads
, int *maxfd
, fd_set
*readfds
,
422 fd_set
*writefds
, fd_set
*exceptfds
,
423 struct timeval
**tv_mod
, struct timeval
*tv_buf
,
424 const struct timeval
*now
);
425 /* Find out file descriptors adns is interested in, and when it would
426 * like the opportunity to time something out. If you do not plan to
427 * block then tv_mod may be 0. Otherwise, tv_mod and tv_buf are as
428 * for adns_firsttimeout. readfds, writefds, exceptfds and maxfd_io may
431 * If *now is not 0 then this will never actually do any I/O, or
432 * change the fds that adns is using or the timeouts it wants. In any
433 * case it won't block.
436 void adns_afterselect(adns_state ads
, int maxfd
, const fd_set
*readfds
,
437 const fd_set
*writefds
, const fd_set
*exceptfds
,
438 const struct timeval
*now
);
439 /* Gives adns flow-of-control for a bit; intended for use after
440 * select. This is just a fancy way of calling adns_processreadable/
441 * writeable/timeouts as appropriate, as if select had returned the
442 * data being passed. Always succeeds.
446 * Example calling sequence:
448 * adns_init _noautosys
454 * adns_submit / adns_check
460 * Entrypoints for poll-loop based asynch io:
464 /* In case your system doesn't have it or you forgot to include
465 * <sys/poll.h>, to stop the following declarations from causing
466 * problems. If your system doesn't have poll then the following
467 * entrypoints will not be defined in libadns. Sorry !
470 int adns_beforepoll(adns_state ads
, struct pollfd
*fds
, int *nfds_io
, int *timeout_io
,
471 const struct timeval
*now
);
472 /* Finds out which fd's adns is interested in, and when it would like
473 * to be able to time things out. This is in a form suitable for use
476 * On entry, usually fds should point to at least *nfds_io structs.
477 * adns will fill up to that many structs will information for poll,
478 * and record in *nfds_io how many structs it filled. If it wants to
479 * listen for more structs then *nfds_io will be set to the number
480 * required and _beforepoll will return ERANGE.
482 * You may call _beforepoll with fds==0 and *nfds_io 0, in which case
483 * adns will fill in the number of fds that it might be interested in
484 * in *nfds_io, and always return either 0 (if it is not interested in
485 * any fds) or ERANGE (if it is).
487 * NOTE that (unless timeout_io is 0) adns may acquire additional fds
488 * from one call to the next, so you must put adns_beforepoll in a
489 * loop, rather than assuming that the second call (with the buffer
490 * size requested by the first) will not return ERANGE.
492 * adns only ever sets POLLIN, POLLOUT and POLLPRI in its pollfd
493 * structs, and only ever looks at those bits. POLLPRI is required to
494 * detect TCP Urgent Data (which should not be used by a DNS server)
495 * so that adns can know that the TCP stream is now useless.
497 * In any case, *timeout_io should be a timeout value as for poll(2),
498 * which adns will modify downwards as required. If the caller does
499 * not plan to block then *timeout_io should be 0 on entry, or
500 * alternatively, timeout_io may be 0. (Alternatively, the caller may
501 * use _beforeselect with timeout_io==0 to find out about file
502 * descriptors, and use _firsttimeout is used to find out when adns
503 * might want to time something out.)
505 * adns_beforepoll will return 0 on success, and will not fail for any
506 * reason other than the fds buffer being too small (ERANGE).
508 * This call will never actually do any I/O, or change the fds that
509 * adns is using or the timeouts it wants; and in any case it won't
513 #define ADNS_POLLFDS_RECOMMENDED 2
514 /* If you allocate an fds buf with at least RECOMMENDED entries then
515 * you are unlikely to need to enlarge it. You are recommended to do
516 * so if it's convenient. However, you must be prepared for adns to
517 * require more space than this.
520 void adns_afterpoll(adns_state ads
, const struct pollfd
*fds
, int nfds
,
521 const struct timeval
*now
);
522 /* Gives adns flow-of-control for a bit; intended for use after
523 * poll(2). fds and nfds should be the results from poll(). pollfd
524 * structs mentioning fds not belonging to adns will be ignored.
528 adns_status
adns_rr_info(adns_rrtype type
,
529 const char **rrtname_r
, const char **fmtname_r
,
531 const void *datap
, char **data_r
);
532 /* Gets information in human-readable (but non-i18n) form
533 * for eg debugging purposes. type must be specified,
534 * and the official name of the corresponding RR type will
535 * be returned in *rrtname_r, and information about the processing
536 * style in *fmtname_r. The length of the table entry in an answer
537 * for that type will be returned in in *len_r.
538 * Any or all of rrtname_r, fmtname_r and len_r may be 0.
539 * If fmtname_r is non-null then *fmtname_r may be
540 * null on return, indicating that no special processing is
543 * data_r be must be non-null iff datap is. In this case
544 * *data_r will be set to point to a human-readable text
545 * string representing the RR data. The text will have
546 * been obtained from malloc() and must be freed by the caller.
548 * Usually this routine will succeed. Possible errors include:
550 * adns_s_rrtypeunknown
551 * adns_s_invaliddata (*datap contained garbage)
552 * If an error occurs then no memory has been allocated,
553 * and *rrtname_r, *fmtname_r, *len_r and *data_r are undefined.
556 const char *adns_strerror(adns_status st
);
557 const char *adns_errabbrev(adns_status st
);
558 /* Like strerror but for adns_status values. adns_errabbrev returns
559 * the abbreviation of the error - eg, for adns_s_timeout it returns
560 * "timeout". You MUST NOT call these functions with status values
561 * not returned by the same adns library.