chiark / gitweb /
7d78bf7ed7dded496ed5e8862bd5569bd7589a01
[adns.git] / src / adns.h
1 /*
2  * adns.h
3  * - adns user-visible API
4  */
5 /*
6  *
7  *  This file is
8  *    Copyright (C) 1997-2000,2003,2006 Ian Jackson
9  *
10  *  It is part of adns, which is
11  *    Copyright (C) 1997-2000,2003,2006 Ian Jackson
12  *    Copyright (C) 1999-2000,2003,2006 Tony Finch
13  *    Copyright (C) 1991 Massachusetts Institute of Technology
14  *
15  *  This program is free software; you can redistribute it and/or modify
16  *  it under the terms of the GNU General Public License as published by
17  *  the Free Software Foundation; either version 2, or (at your option)
18  *  any later version.
19  *  
20  *  This program is distributed in the hope that it will be useful,
21  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
22  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
23  *  GNU General Public License for more details.
24  *
25  * 
26  *  For the benefit of certain LGPL'd `omnibus' software which
27  *  provides a uniform interface to various things including adns, I
28  *  make the following additional licence.  I do this because the GPL
29  *  would otherwise force either the omnibus software to be GPL'd or
30  *  the adns-using part to be distributed separately.
31  *  
32  *  So: you may also redistribute and/or modify adns.h (but only the
33  *  public header file adns.h and not any other part of adns) under the
34  *  terms of the GNU Library General Public License as published by the
35  *  Free Software Foundation; either version 2 of the License, or (at
36  *  your option) any later version.
37  *  
38  *  Note that adns itself is GPL'd.  Authors of adns-using applications
39  *  with GPL-incompatible licences, and people who distribute adns with
40  *  applications where the whole distribution is not GPL'd, are still
41  *  likely to be in violation of the GPL.  Anyone who wants to do this
42  *  should contact Ian Jackson.  Please note that to avoid encouraging
43  *  people to infringe the GPL as it applies to the body of adns, Ian
44  *  thinks that if you take advantage of the special exception to
45  *  redistribute just adns.h under the LGPL, you should retain this
46  *  paragraph in its place in the appropriate copyright statements.
47  *
48  *
49  *  You should have received a copy of the GNU General Public License,
50  *  or the GNU Library General Public License, as appropriate, along
51  *  with this program; if not, write to the Free Software Foundation,
52  *  Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
53  *
54  *
55  *  $Id$
56  */
57
58 #ifndef ADNS_H_INCLUDED
59 #define ADNS_H_INCLUDED
60
61 #include <stdio.h>
62 #include <stdarg.h>
63
64 #include <sys/types.h>
65 #include <sys/socket.h>
66 #include <netinet/in.h>
67 #include <sys/time.h>
68 #include <unistd.h>
69 #include <net/if.h>
70
71 #ifdef __cplusplus
72 extern "C" { /* I really dislike this - iwj. */
73 #endif
74
75 /* All struct in_addr anywhere in adns are in NETWORK byte order. */
76
77 typedef struct adns__state *adns_state;
78 typedef struct adns__query *adns_query;
79
80 typedef enum { /* In general, or together the desired flags: */
81  adns_if_none=        0x0000,/* no flags.  nicer than 0 for some compilers */
82  adns_if_noenv=       0x0001,/* do not look at environment */
83  adns_if_noerrprint=  0x0002,/* never print to stderr (_debug overrides) */
84  adns_if_noserverwarn=0x0004,/* do not warn to stderr about duff servers etc */
85  adns_if_debug=       0x0008,/* enable all output to stderr plus debug msgs */
86  adns_if_logpid=      0x0080,/* include pid in diagnostic output */
87  adns_if_noautosys=   0x0010,/* do not make syscalls at every opportunity */
88  adns_if_eintr=       0x0020,/* allow _wait and _synchronous to return EINTR */
89  adns_if_nosigpipe=   0x0040,/* applic has SIGPIPE ignored, do not protect */
90  adns_if_checkc_entex=0x0100,/* consistency checks on entry/exit to adns fns */
91  adns_if_checkc_freq= 0x0300 /* consistency checks very frequently (slow!) */
92 } adns_initflags;
93
94 typedef enum { /* In general, or together the desired flags: */
95  adns_qf_none=           0x00000000,/* no flags */
96  adns_qf_search=         0x00000001,/* use the searchlist */
97  adns_qf_usevc=          0x00000002,/* use a virtual circuit (TCP conn) */
98  adns_qf_owner=          0x00000004,/* fill in the owner field in the answer */
99  adns_qf_quoteok_query=  0x00000010,/* allow special chars in query domain */
100  adns_qf_quoteok_cname=  0x00000000,/*  ... in CNAME we go via (now default) */
101  adns_qf_quoteok_anshost=0x00000040,/*  ... in things supposedly hostnames */
102  adns_qf_quotefail_cname=0x00000080,/* refuse if quote-req chars in CNAME we go via */
103  adns_qf_cname_loose=    0x00000100,/* allow refs to CNAMEs - without, get _s_cname */
104  adns_qf_cname_forbid=   0x00000200,/* don't follow CNAMEs, instead give _s_cname */
105  adns_qf_ipv6_mapv4=     0x00001000,/*  ... return IPv4 addresses as v6-mapped */
106  adns_qf_addrlit_scope_forbid=0x00002000,/* forbid %<scope> in IPv6 literals */
107  adns_qf_addrlit_scope_numeric=0x00004000,/* %<scope> may only be numeric */
108  adns_qf_addrlit_ipv4_quadonly=0x00008000,/* reject non-dotted-quad ipv4 */
109  adns__qf_internalmask=  0x0ff00000
110 } adns_queryflags;
111
112 typedef enum {
113  adns_rrt_typemask=  0x0ffff,
114  adns_rrt_reprmask= 0xffffff,
115  adns__qtf_deref_bit=0x10000,/* internal version of ..._deref below */
116  adns__qtf_mail822=  0x20000,/* return mailboxes in RFC822 rcpt field fmt   */
117
118  adns__qtf_bigaddr=0x1000000,/* use the new larger sockaddr union */
119
120  adns__qtf_deref=    adns__qtf_deref_bit|adns__qtf_bigaddr
121                             ,/* dereference domains; perhaps get extra data */
122
123  adns_r_unknown=     0x40000,
124    /* To use this, ask for records of type   <rr-type-code>|adns_r_unknown.
125     * adns will not process the RDATA - you'll get adns_rr_byteblocks,
126     * where the int is the length and the unsigned char* points to the
127     * data.  String representation of the RR data (by adns_rrinfo) is as in
128     * RFC3597.  adns_rr_info will not return the type name in *rrtname_r
129     * (due to memory management problems); *fmtname_r will be set to
130     * "unknown".
131     *
132     * Do not specify adns_r_unknown along with a known RR type which
133     * requires domain name uncompression (see RFC3597 s4); domain names
134     * will not be uncompressed and the resulting data would be useless.
135     * Asking for meta-RR types via adns_r_unknown will not work properly
136     * either and may make adns complain about server misbehaviour, so don't
137     * do that.
138     *
139     * Don't forget adns_qf_quoteok if that's what you want. */
140
141  adns_r_none=             0,
142                      
143  adns_r_a=                1,
144                      
145  adns_r_ns_raw=           2,
146  adns_r_ns=                  adns_r_ns_raw|adns__qtf_deref,
147                      
148  adns_r_cname=            5,
149                      
150  adns_r_soa_raw=          6,
151  adns_r_soa=                 adns_r_soa_raw|adns__qtf_mail822, 
152                      
153  adns_r_ptr_raw=         12, /* do not mind PTR with wrong or missing A */
154  adns_r_ptr=                 adns_r_ptr_raw|adns__qtf_deref,
155                      
156  adns_r_hinfo=           13,  
157                      
158  adns_r_mx_raw=          15,
159  adns_r_mx=                  adns_r_mx_raw|adns__qtf_deref,
160                      
161  adns_r_txt=             16,
162                      
163  adns_r_rp_raw=          17,
164  adns_r_rp=                  adns_r_rp_raw|adns__qtf_mail822,
165
166  adns_r_aaaa=            28,
167
168  /* For SRV records, query domain without _qf_quoteok_query must look
169   * as expected from SRV RFC with hostname-like Name.  _With_
170   * _quoteok_query, any query domain is allowed. */
171  adns_r_srv_raw=         33,
172  adns_r_srv=                 adns_r_srv_raw|adns__qtf_deref,
173                      
174  adns_r_addr=                adns_r_a|adns__qtf_deref
175  
176 } adns_rrtype;
177
178 /*
179  * In queries without qf_quoteok_*, all domains must have standard
180  * legal syntax, or you get adns_s_querydomainvalid (if the query
181  * domain contains bad characters) or adns_s_answerdomaininvalid (if
182  * the answer contains bad characters).
183  * 
184  * In queries _with_ qf_quoteok_*, domains in the query or response
185  * may contain any characters, quoted according to RFC1035 5.1.  On
186  * input to adns, the char* is a pointer to the interior of a "
187  * delimited string, except that " may appear in it unquoted.  On
188  * output, the char* is a pointer to a string which would be legal
189  * either inside or outside " delimiters; any character which isn't
190  * legal in a hostname (ie alphanumeric or hyphen) or one of _ / +
191  * (the three other punctuation characters commonly abused in domain
192  * names) will be quoted, as \X if it is a printing ASCII character or
193  * \DDD otherwise.
194  *
195  * If the query goes via a CNAME then the canonical name (ie, the
196  * thing that the CNAME record refers to) is usually allowed to
197  * contain any characters, which will be quoted as above.  With
198  * adns_qf_quotefail_cname you get adns_s_answerdomaininvalid when
199  * this happens.  (This is a change from version 0.4 and earlier, in
200  * which failing the query was the default, and you had to say
201  * adns_qf_quoteok_cname to avoid this; that flag is now deprecated.)
202  *
203  * In version 0.4 and earlier, asking for _raw records containing
204  * mailboxes without specifying _qf_quoteok_anshost was silly.  This
205  * is no longer the case.  In this version only parts of responses
206  * that are actually supposed to be hostnames will be refused by
207  * default if quote-requiring characters are found.
208  */
209
210 /*
211  * If you ask for an RR which contains domains which are actually
212  * encoded mailboxes, and don't ask for the _raw version, then adns
213  * returns the mailbox formatted suitably for an RFC822 recipient
214  * header field.  The particular format used is that if the mailbox
215  * requires quoting according to the rules in RFC822 then the
216  * local-part is quoted in double quotes, which end at the next
217  * unescaped double quote (\ is the escape char, and is doubled, and
218  * is used to escape only \ and ").  If the local-part is legal
219  * without quoting according to RFC822, it is presented as-is.  In any
220  * case the local-part is followed by an @ and the domain.  The domain
221  * will not contain any characters not legal in hostnames.
222  *
223  * Unquoted local-parts may contain any printing 7-bit ASCII
224  * except the punctuation characters ( ) < > @ , ; : \ " [ ]
225  * I.e. they may contain alphanumerics, and the following
226  * punctuation characters:  ! # % ^ & * - _ = + { } .
227  *
228  * adns will reject local parts containing control characters (byte
229  * values 0-31, 127-159, and 255) - these appear to be legal according
230  * to RFC822 (at least 0-127) but are clearly a bad idea.  RFC1035
231  * syntax does not make any distinction between a single RFC822
232  * quoted-string containing full stops, and a series of quoted-strings
233  * separated by full stops; adns will return anything that isn't all
234  * valid atoms as a single quoted-string.  RFC822 does not allow
235  * high-bit-set characters at all, but adns does allow them in
236  * local-parts, treating them as needing quoting.
237  *
238  * If you ask for the domain with _raw then _no_ checking is done
239  * (even on the host part, regardless of adns_qf_quoteok_anshost), and
240  * you just get the domain name in master file format.
241  *
242  * If no mailbox is supplied the returned string will be `.' in either
243  * case.
244  */
245
246 typedef enum {
247  adns_s_ok,
248
249  /* locally induced errors */
250  adns_s_nomemory,
251  adns_s_unknownrrtype,
252  adns_s_systemfail,
253
254  adns_s_max_localfail= 29,
255  
256  /* remotely induced errors, detected locally */
257  adns_s_timeout,
258  adns_s_allservfail,
259  adns_s_norecurse,
260  adns_s_invalidresponse,
261  adns_s_unknownformat,
262
263  adns_s_max_remotefail= 59,
264  
265  /* remotely induced errors, reported by remote server to us */
266  adns_s_rcodeservfail,
267  adns_s_rcodeformaterror,
268  adns_s_rcodenotimplemented,
269  adns_s_rcoderefused,
270  adns_s_rcodeunknown,
271
272  adns_s_max_tempfail= 99,
273
274  /* remote configuration errors */
275  adns_s_inconsistent, /* PTR gives domain whose A does not exist and match */
276  adns_s_prohibitedcname, /* CNAME, but eg A expected (not if _qf_loosecname) */
277  adns_s_answerdomaininvalid,
278  adns_s_answerdomaintoolong,
279  adns_s_invaliddata,
280  
281  adns_s_max_misconfig= 199,
282
283  /* permanent problems with the query */
284  adns_s_querydomainwrong,
285  adns_s_querydomaininvalid,
286  adns_s_querydomaintoolong,
287  
288  adns_s_max_misquery= 299,
289
290  /* permanent errors */
291  adns_s_nxdomain,
292  adns_s_nodata,
293
294  adns_s_max_permfail= 499
295  
296 } adns_status;
297
298 typedef union {
299   struct sockaddr sa;
300   struct sockaddr_in inet;
301 } adns_sockaddr_v4only;
302
303 typedef union {
304   struct sockaddr sa;
305   struct sockaddr_in inet;
306   struct sockaddr_in6 inet6;
307 } adns_sockaddr;
308
309 typedef struct {
310   int len;
311   adns_sockaddr addr;
312 } adns_rr_addr;
313
314 typedef struct {
315   /* the old v4-only structure; handy if you have complicated binary
316    * compatibility problems. */
317   int len;
318   adns_sockaddr_v4only addr;
319 } adns_rr_addr_v4only;
320
321 typedef struct {
322   char *host;
323   adns_status astatus;
324   int naddrs; /* temp fail => -1, perm fail => 0, s_ok => >0 */
325   adns_rr_addr *addrs;
326 } adns_rr_hostaddr;
327
328 typedef struct {
329   char *(array[2]);
330 } adns_rr_strpair;
331
332 typedef struct {
333   int i;
334   adns_rr_hostaddr ha;
335 } adns_rr_inthostaddr;
336
337 typedef struct {
338   /* Used both for mx_raw, in which case i is the preference and str
339    * the domain, and for txt, in which case each entry has i for the
340    * `text' length, and str for the data (which will have had an extra
341    * nul appended so that if it was plain text it is now a
342    * null-terminated string).
343    */
344   int i;
345   char *str;
346 } adns_rr_intstr;
347
348 typedef struct {
349   adns_rr_intstr array[2];
350 } adns_rr_intstrpair;
351
352 typedef struct {
353   char *mname, *rname;
354   unsigned long serial, refresh, retry, expire, minimum;
355 } adns_rr_soa;
356
357 typedef struct {
358   int priority, weight, port;
359   char *host;
360 } adns_rr_srvraw;
361
362 typedef struct {
363   int priority, weight, port;
364   adns_rr_hostaddr ha;
365 } adns_rr_srvha;
366
367 typedef struct {
368   int len;
369   unsigned char *data;
370 } adns_rr_byteblock;
371
372 typedef struct {
373   adns_status status;
374   char *cname; /* always NULL if query was for CNAME records */
375   char *owner; /* only set if req'd in query flags; maybe 0 on error anyway */
376   adns_rrtype type; /* guaranteed to be same as in query */
377   time_t expires;/*abs time.  def only if _s_ok, nxdomain or nodata. NOT TTL!*/
378   int nrrs, rrsz; /* nrrs is 0 if an error occurs */
379   union {
380     void *untyped;
381     unsigned char *bytes;
382     char *(*str);                    /* ns_raw, cname, ptr, ptr_raw */
383     adns_rr_intstr *(*manyistr);     /* txt (list strs ends with i=-1, str=0)*/
384     adns_rr_addr *addr;              /* addr */
385     struct in_addr *inaddr;          /* a */
386     struct in6_addr *in6addr;        /* aaaa */
387     adns_rr_hostaddr *hostaddr;      /* ns */
388     adns_rr_intstrpair *intstrpair;  /* hinfo */
389     adns_rr_strpair *strpair;        /* rp, rp_raw */
390     adns_rr_inthostaddr *inthostaddr;/* mx */
391     adns_rr_intstr *intstr;          /* mx_raw */
392     adns_rr_soa *soa;                /* soa, soa_raw */
393     adns_rr_srvraw *srvraw;          /* srv_raw */
394     adns_rr_srvha *srvha;/* srv */
395     adns_rr_byteblock *byteblock;    /* ...|unknown */
396   } rrs;
397 } adns_answer;
398
399 /* Memory management:
400  *  adns_state and adns_query are actually pointers to malloc'd state;
401  *  On submission questions are copied, including the owner domain;
402  *  Answers are malloc'd as a single piece of memory; pointers in the
403  *  answer struct point into further memory in the answer.
404  * query_io:
405  *  Must always be non-null pointer;
406  *  If *query_io is 0 to start with then any query may be returned;
407  *  If *query_io is !0 adns_query then only that query may be returned.
408  *  If the call is successful, *query_io, *answer_r, and *context_r
409  *  will all be set.
410  * Errors:
411  *  Return values are 0 or an errno value.
412  *
413  *  For _init, _init_strcfg, _submit and _synchronous, system errors
414  *  (eg, failure to create sockets, malloc failure, etc.) return errno
415  *  values.  EINVAL from _init et al means the configuration file
416  *  is erroneous and cannot be parsed.
417  * 
418  *  For _wait and _check failures are reported in the answer
419  *  structure, and only 0, ESRCH or (for _check) EAGAIN is
420  *  returned: if no (appropriate) requests are done adns_check returns
421  *  EAGAIN; if no (appropriate) requests are outstanding both
422  *  adns_query and adns_wait return ESRCH.
423  *
424  *  Additionally, _wait can return EINTR if you set adns_if_eintr.
425  *
426  *  All other errors (nameserver failure, timed out connections, &c)
427  *  are returned in the status field of the answer.  After a
428  *  successful _wait or _check, if status is nonzero then nrrs will be
429  *  0, otherwise it will be >0.  type will always be the type
430  *  requested.
431  */
432
433 /* Threads:
434  *  adns does not use any static modifiable state, so it
435  *   is safe to call adns_init several times and then use the
436  *   resulting adns_states concurrently.
437  *  However, it is NOT safe to make simultaneous calls into
438  *   adns using the same adns_state; a single adns_state must be used
439  *   only by one thread at a time.  You can solve this problem by
440  *   having one adns_state per thread, or if that isn't feasible, you
441  *   could maintain a pool of adns_states.  Unfortunately neither of
442  *   these approaches has optimal performance.
443  */
444
445 int adns_init(adns_state *newstate_r, adns_initflags flags,
446               FILE *diagfile /*0=>stderr*/);
447
448 int adns_init_strcfg(adns_state *newstate_r, adns_initflags flags,
449                      FILE *diagfile /*0=>discard*/, const char *configtext);
450
451 typedef void adns_logcallbackfn(adns_state ads, void *logfndata,
452                                 const char *fmt, va_list al);
453   /* Will be called perhaps several times for each message; when the
454    * message is complete, the string implied by fmt and al will end in
455    * a newline.  Log messages start with `adns debug:' or `adns
456    * warning:' or `adns:' (for errors), or `adns debug [PID]:'
457    * etc. if adns_if_logpid is set. */
458
459 int adns_init_logfn(adns_state *newstate_r, adns_initflags flags,
460                     const char *configtext /*0=>use default config files*/,
461                     adns_logcallbackfn *logfn /*0=>logfndata is a FILE* */,
462                     void *logfndata /*0 with logfn==0 => discard*/);
463
464 /* Configuration:
465  *  adns_init reads /etc/resolv.conf, which is expected to be (broadly
466  *  speaking) in the format expected by libresolv, and then
467  *  /etc/resolv-adns.conf if it exists.  adns_init_strcfg is instead
468  *  passed a string which is interpreted as if it were the contents of
469  *  resolv.conf or resolv-adns.conf.  In general, configuration which
470  *  is set later overrides any that is set earlier.
471  *
472  * Standard directives understood in resolv[-adns].conf:
473  * 
474  *  nameserver <address>
475  *   Must be followed by the IP address of a nameserver.  Several
476  *   nameservers may be specified, and they will be tried in the order
477  *   found.  There is a compiled in limit, currently 5, on the number
478  *   of nameservers.  (libresolv supports only 3 nameservers.)
479  *
480  *  search <domain> ...
481  *   Specifies the search list for queries which specify
482  *   adns_qf_search.  This is a list of domains to append to the query
483  *   domain.  The query domain will be tried as-is either before all
484  *   of these or after them, depending on the ndots option setting
485  *   (see below).
486  *
487  *  domain <domain>
488  *   This is present only for backward compatibility with obsolete
489  *   versions of libresolv.  It should not be used, and is interpreted
490  *   by adns as if it were `search' - note that this is subtly
491  *   different to libresolv's interpretation of this directive.
492  *
493  *  sortlist <addr>/<mask> ...
494  *   Should be followed by a sequence of IP-address and netmask pairs,
495  *   separated by spaces.  They may be specified as
496  *   eg. 172.30.206.0/24 or 172.30.206.0/255.255.255.0.  Currently up
497  *   to 15 pairs may be specified (but note that libresolv only
498  *   supports up to 10).
499  *
500  *  options
501  *   Should followed by one or more options, separated by spaces.
502  *   Each option consists of an option name, followed by optionally
503  *   a colon and a value.  Options are listed below.
504  *
505  * Non-standard directives understood in resolv[-adns].conf:
506  *
507  *  clearnameservers
508  *   Clears the list of nameservers, so that further nameserver lines
509  *   start again from the beginning.
510  *
511  *  include <filename>
512  *   The specified file will be read.
513  *
514  * Additionally, adns will ignore lines in resolv[-adns].conf which
515  * start with a #.
516  *
517  * Standard options understood:
518  *
519  *  debug
520  *   Enables debugging output from the resolver, which will be written
521  *   to stderr.
522  *
523  *  ndots:<count>
524  *   Affects whether queries with adns_qf_search will be tried first
525  *   without adding domains from the searchlist, or whether the bare
526  *   query domain will be tried last.  Queries which contain at least
527  *   <count> dots will be tried bare first.  The default is 1.
528  *
529  * Non-standard options understood:
530  *
531  *  adns_checkc:none
532  *  adns_checkc:entex
533  *  adns_checkc:freq
534  *   Changes the consistency checking frequency; this overrides the
535  *   setting of adns_if_check_entex, adns_if_check_freq, or neither,
536  *   in the flags passed to adns_init.
537  * 
538  * There are a number of environment variables which can modify the
539  * behaviour of adns.  They take effect only if adns_init is used, and
540  * the caller of adns_init can disable them using adns_if_noenv.  In
541  * each case there is both a FOO and an ADNS_FOO; the latter is
542  * interpreted later so that it can override the former.  Unless
543  * otherwise stated, environment variables are interpreted after
544  * resolv[-adns].conf are read, in the order they are listed here.
545  *
546  *  RES_CONF, ADNS_RES_CONF
547  *   A filename, whose contets are in the format of resolv.conf.
548  *
549  *  RES_CONF_TEXT, ADNS_RES_CONF_TEXT
550  *   A string in the format of resolv.conf.
551  *
552  *  RES_OPTIONS, ADNS_RES_OPTIONS
553  *   These are parsed as if they appeared in the `options' line of a
554  *   resolv.conf.  In addition to being parsed at this point in the
555  *   sequence, they are also parsed at the very beginning before
556  *   resolv.conf or any other environment variables are read, so that
557  *   any debug option can affect the processing of the configuration.
558  *
559  *  LOCALDOMAIN, ADNS_LOCALDOMAIN
560  *   These are interpreted as if their contents appeared in a `search'
561  *   line in resolv.conf.
562  */
563
564 int adns_synchronous(adns_state ads,
565                      const char *owner,
566                      adns_rrtype type,
567                      adns_queryflags flags,
568                      adns_answer **answer_r);
569
570 /* NB: if you set adns_if_noautosys then _submit and _check do not
571  * make any system calls; you must use some of the asynch-io event
572  * processing functions to actually get things to happen.
573  */
574
575 int adns_submit(adns_state ads,
576                 const char *owner,
577                 adns_rrtype type,
578                 adns_queryflags flags,
579                 void *context,
580                 adns_query *query_r);
581
582 /* The owner should be quoted in master file format. */
583
584 int adns_check(adns_state ads,
585                adns_query *query_io,
586                adns_answer **answer_r,
587                void **context_r);
588
589 int adns_wait(adns_state ads,
590               adns_query *query_io,
591               adns_answer **answer_r,
592               void **context_r);
593
594 /* same as adns_wait but uses poll(2) internally */
595 int adns_wait_poll(adns_state ads,
596                    adns_query *query_io,
597                    adns_answer **answer_r,
598                    void **context_r);
599
600 void adns_cancel(adns_query query);
601
602 /* The adns_query you get back from _submit is valid (ie, can be
603  * legitimately passed into adns functions) until it is returned by
604  * adns_check or adns_wait, or passed to adns_cancel.  After that it
605  * must not be used.  You can rely on it not being reused until the
606  * first adns_submit or _transact call using the same adns_state after
607  * it became invalid, so you may compare it for equality with other
608  * query handles until you next call _query or _transact.
609  *
610  * _submit and _synchronous return ENOSYS if they don't understand the
611  * query type.
612  */
613
614 int adns_submit_reverse(adns_state ads,
615                         const struct sockaddr *addr,
616                         adns_rrtype type,
617                         adns_queryflags flags,
618                         void *context,
619                         adns_query *query_r);
620 /* type must be _r_ptr or _r_ptr_raw.  _qf_search is ignored.
621  * addr->sa_family must be AF_INET or you get ENOSYS.
622  */
623
624 int adns_submit_reverse_any(adns_state ads,
625                             const struct sockaddr *addr,
626                             const char *rzone,
627                             adns_rrtype type,
628                             adns_queryflags flags,
629                             void *context,
630                             adns_query *query_r);
631 /* For RBL-style reverse `zone's; look up
632  *   <reversed-address>.<zone>
633  * Any type is allowed.  _qf_search is ignored.
634  * addr->sa_family must be AF_INET or you get ENOSYS.
635  */
636
637 void adns_finish(adns_state ads);
638 /* You may call this even if you have queries outstanding;
639  * they will be cancelled.
640  */
641
642 #define ADNS_ADDR2TEXT_BUFLEN                                   \
643   (INET6_ADDRSTRLEN + 1/*%*/                                    \
644   + ((IF_NAMESIZE-1) > 9 ? (IF_NAMESIZE-1) : 9/*uint32*/)       \
645   + 1/* nul; included in IF_NAMESIZE */)
646
647 int adns_text2addr(const char *text, uint16_t port, adns_queryflags flags,
648                    struct sockaddr *sa_r,
649                    socklen_t *salen_io /* updated iff OK or ENOSPC */);
650 int adns_addr2text(const struct sockaddr *sa, adns_queryflags flags,
651                    char *buffer, int *buflen_io /* updated ONLY on ENOSPC */,
652                    int *port_r /* may be 0 */);
653   /*
654    * port is always in host byte order and is simply copied to and
655    * from the appropriate sockaddr field (byteswapped as necessary).
656    *
657    * The only flags supported are adns_qf_addrlit_...; others are
658    * ignored.
659    *
660    * Error return values are:
661    *
662    *  ENOSPC    Output buffer is too small.  Can only happen if
663    *            *buflen_io < ADNS_ADDR2TEXT_BUFLEN or
664    *            *salen_io < sizeof(adns_sockaddr).  On return,
665    *            *buflen_io or *salen_io has been updated by adns.
666    *
667    *  EINVAL    text has invalid syntax.
668    *
669    *            text represents an address family not supported by
670    *            this version of adns.
671    *
672    *            Scoped address supplied (text contained "%" or
673    *            sin6_scope_id nonzero) but caller specified
674    *            adns_qf_addrlit_scope_forbid.
675    *
676    *            Scope name (rather than number) supplied in text but
677    *            caller specified adns_qf_addrlit_scope_numeric.
678    *
679    *  EAFNOSUPPORT   sa->sa_family is not supported (addr2text only).
680    *
681    * Only if neither adns_qf_addrlit_scope_forbid nor
682    * adns_qf_addrlit_scope_numeric are set:
683    *
684    *  ENOSYS    Scope name supplied in text but IPv6 address part of
685    *            sockaddr is not a link local address.
686    *
687    *  ENXIO     Scope name supplied in text but if_nametoindex
688    *            said it wasn't a valid local interface name.
689    *
690    *  EIO       Scoped address supplied but if_nametoindex failed
691    *            in an unexpected way; adns has printed a message to
692    *            stderr.
693    *
694    *  any other   if_nametoindex failed in a more-or-less expected way.
695    */
696
697 void adns_forallqueries_begin(adns_state ads);
698 adns_query adns_forallqueries_next(adns_state ads, void **context_r);
699 /* Iterator functions, which you can use to loop over the outstanding
700  * (submitted but not yet successfuly checked/waited) queries.
701  *
702  * You can only have one iteration going at once.  You may call _begin
703  * at any time; after that, an iteration will be in progress.  You may
704  * only call _next when an iteration is in progress - anything else
705  * may coredump.  The iteration remains in progress until _next
706  * returns 0, indicating that all the queries have been walked over,
707  * or ANY other adns function is called with the same adns_state (or a
708  * query in the same adns_state).  There is no need to explicitly
709  * finish an iteration.
710  *
711  * context_r may be 0.  *context_r may not be set when _next returns 0.
712  */
713
714 void adns_checkconsistency(adns_state ads, adns_query qu);
715 /* Checks the consistency of adns's internal data structures.
716  * If any error is found, the program will abort().
717  * You may pass 0 for qu; if you pass non-null then additional checks
718  * are done to make sure that qu is a valid query.
719  */
720
721 /*
722  * Example expected/legal calling sequence for submit/check/wait:
723  *  adns_init
724  *  adns_submit 1
725  *  adns_submit 2
726  *  adns_submit 3
727  *  adns_wait 1
728  *  adns_check 3 -> EAGAIN
729  *  adns_wait 2
730  *  adns_wait 3
731  *  ....
732  *  adns_finish
733  */
734
735 /*
736  * Entrypoints for generic asynch io:
737  * (these entrypoints are not very useful except in combination with *
738  * some of the other I/O model calls which can tell you which fds to
739  * be interested in):
740  *
741  * Note that any adns call may cause adns to open and close fds, so
742  * you must call beforeselect or beforepoll again just before
743  * blocking, or you may not have an up-to-date list of it's fds.
744  */
745
746 int adns_processany(adns_state ads);
747 /* Gives adns flow-of-control for a bit.  This will never block, and
748  * can be used with any threading/asynch-io model.  If some error
749  * occurred which might cause an event loop to spin then the errno
750  * value is returned.
751  */
752
753 int adns_processreadable(adns_state ads, int fd, const struct timeval *now);
754 int adns_processwriteable(adns_state ads, int fd, const struct timeval *now);
755 int adns_processexceptional(adns_state ads, int fd, const struct timeval *now);
756 /* Gives adns flow-of-control so that it can process incoming data
757  * from, or send outgoing data via, fd.  Very like _processany.  If it
758  * returns zero then fd will no longer be readable or writeable
759  * (unless of course more data has arrived since).  adns will _only_
760  * use that fd and only in the manner specified, regardless of whether
761  * adns_if_noautosys was specified.
762  *
763  * adns_processexceptional should be called when select(2) reports an
764  * exceptional condition, or poll(2) reports POLLPRI.
765  *
766  * It is fine to call _processreabable or _processwriteable when the
767  * fd is not ready, or with an fd that doesn't belong to adns; it will
768  * then just return 0.
769  *
770  * If some error occurred which might prevent an event loop to spin
771  * then the errno value is returned.
772  */
773
774 void adns_processtimeouts(adns_state ads, const struct timeval *now);
775 /* Gives adns flow-of-control so that it can process any timeouts
776  * which might have happened.  Very like _processreadable/writeable.
777  *
778  * now may be 0; if it isn't, *now must be the current time, recently
779  * obtained from gettimeofday.
780  */
781
782 void adns_firsttimeout(adns_state ads,
783                        struct timeval **tv_mod, struct timeval *tv_buf,
784                        struct timeval now);
785 /* Asks adns when it would first like the opportunity to time
786  * something out.  now must be the current time, from gettimeofday.
787  * 
788  * If tv_mod points to 0 then tv_buf must be non-null, and
789  * _firsttimeout will fill in *tv_buf with the time until the first
790  * timeout, and make *tv_mod point to tv_buf.  If adns doesn't have
791  * anything that might need timing out it will leave *tv_mod as 0.
792  *
793  * If *tv_mod is not 0 then tv_buf is not used.  adns will update
794  * *tv_mod if it has any earlier timeout, and leave it alone if it
795  * doesn't.
796  *
797  * This call will not actually do any I/O, or change the fds that adns
798  * is using.  It always succeeds and never blocks.
799  */
800
801 void adns_globalsystemfailure(adns_state ads);
802 /* If serious problem(s) happen which globally affect your ability to
803  * interact properly with adns, or adns's ability to function
804  * properly, you or adns can call this function.
805  *
806  * All currently outstanding queries will be made to fail with
807  * adns_s_systemfail, and adns will close any stream sockets it has
808  * open.
809  *
810  * This is used by adns, for example, if gettimeofday() fails.
811  * Without this the program's event loop might start to spin !
812  *
813  * This call will never block.
814  */
815
816 /*
817  * Entrypoints for select-loop based asynch io:
818  */
819
820 void adns_beforeselect(adns_state ads, int *maxfd, fd_set *readfds,
821                        fd_set *writefds, fd_set *exceptfds,
822                        struct timeval **tv_mod, struct timeval *tv_buf,
823                        const struct timeval *now);
824 /* Find out file descriptors adns is interested in, and when it would
825  * like the opportunity to time something out.  If you do not plan to
826  * block then tv_mod may be 0.  Otherwise, tv_mod and tv_buf are as
827  * for adns_firsttimeout.  readfds, writefds, exceptfds and maxfd_io may
828  * not be 0.
829  *
830  * If tv_mod is 0 on entry then this will never actually do any I/O,
831  * or change the fds that adns is using or the timeouts it wants.  In
832  * any case it won't block, and it will set the timeout to zero if a
833  * query finishes in _beforeselect.
834  */
835
836 void adns_afterselect(adns_state ads, int maxfd, const fd_set *readfds,
837                       const fd_set *writefds, const fd_set *exceptfds,
838                       const struct timeval *now);
839 /* Gives adns flow-of-control for a bit; intended for use after
840  * select.  This is just a fancy way of calling adns_processreadable/
841  * writeable/timeouts as appropriate, as if select had returned the
842  * data being passed.  Always succeeds.
843  */
844
845 /*
846  * Example calling sequence:
847  *
848  *  adns_init _noautosys
849  *  loop {
850  *   adns_beforeselect
851  *   select
852  *   adns_afterselect
853  *   ...
854  *   adns_submit / adns_check
855  *   ...
856  *  }
857  */
858
859 /*
860  * Entrypoints for poll-loop based asynch io:
861  */
862
863 struct pollfd;
864 /* In case your system doesn't have it or you forgot to include
865  * <sys/poll.h>, to stop the following declarations from causing
866  * problems.  If your system doesn't have poll then the following
867  * entrypoints will not be defined in libadns.  Sorry !
868  */
869
870 int adns_beforepoll(adns_state ads, struct pollfd *fds,
871                     int *nfds_io, int *timeout_io,
872                     const struct timeval *now);
873 /* Finds out which fd's adns is interested in, and when it would like
874  * to be able to time things out.  This is in a form suitable for use
875  * with poll(2).
876  * 
877  * On entry, usually fds should point to at least *nfds_io structs.
878  * adns will fill up to that many structs will information for poll,
879  * and record in *nfds_io how many structs it filled.  If it wants to
880  * listen for more structs then *nfds_io will be set to the number
881  * required and _beforepoll will return ERANGE.
882  *
883  * You may call _beforepoll with fds==0 and *nfds_io 0, in which case
884  * adns will fill in the number of fds that it might be interested in
885  * in *nfds_io, and always return either 0 (if it is not interested in
886  * any fds) or ERANGE (if it is).
887  *
888  * NOTE that (unless now is 0) adns may acquire additional fds
889  * from one call to the next, so you must put adns_beforepoll in a
890  * loop, rather than assuming that the second call (with the buffer
891  * size requested by the first) will not return ERANGE.
892  *
893  * adns only ever sets POLLIN, POLLOUT and POLLPRI in its pollfd
894  * structs, and only ever looks at those bits.  POLLPRI is required to
895  * detect TCP Urgent Data (which should not be used by a DNS server)
896  * so that adns can know that the TCP stream is now useless.
897  *
898  * In any case, *timeout_io should be a timeout value as for poll(2),
899  * which adns will modify downwards as required.  If the caller does
900  * not plan to block then *timeout_io should be 0 on entry, or
901  * alternatively, timeout_io may be 0.  (Alternatively, the caller may
902  * use _beforeselect with timeout_io==0 to find out about file
903  * descriptors, and use _firsttimeout is used to find out when adns
904  * might want to time something out.)
905  *
906  * adns_beforepoll will return 0 on success, and will not fail for any
907  * reason other than the fds buffer being too small (ERANGE).
908  *
909  * This call will never actually do any I/O.  If you supply the
910  * current time it will not change the fds that adns is using or the
911  * timeouts it wants.
912  *
913  * In any case this call won't block.
914  */
915
916 #define ADNS_POLLFDS_RECOMMENDED 3
917 /* If you allocate an fds buf with at least RECOMMENDED entries then
918  * you are unlikely to need to enlarge it.  You are recommended to do
919  * so if it's convenient.  However, you must be prepared for adns to
920  * require more space than this.
921  */
922
923 void adns_afterpoll(adns_state ads, const struct pollfd *fds, int nfds,
924                     const struct timeval *now);
925 /* Gives adns flow-of-control for a bit; intended for use after
926  * poll(2).  fds and nfds should be the results from poll().  pollfd
927  * structs mentioning fds not belonging to adns will be ignored.
928  */
929
930
931 adns_status adns_rr_info(adns_rrtype type,
932                          const char **rrtname_r, const char **fmtname_r,
933                          int *len_r,
934                          const void *datap, char **data_r);
935 /*
936  * Get information about a query type, or convert reply data to a
937  * textual form.  type must be specified, and the official name of the
938  * corresponding RR type will be returned in *rrtname_r, and
939  * information about the processing style in *fmtname_r.  The length
940  * of the table entry in an answer for that type will be returned in
941  * in *len_r.  Any or all of rrtname_r, fmtname_r and len_r may be 0.
942  * If fmtname_r is non-null then *fmtname_r may be null on return,
943  * indicating that no special processing is involved.
944  *
945  * data_r be must be non-null iff datap is.  In this case *data_r will
946  * be set to point to a string pointing to a representation of the RR
947  * data in master file format.  (The owner name, timeout, class and
948  * type will not be present - only the data part of the RR.)  The
949  * memory will have been obtained from malloc() and must be freed by
950  * the caller.
951  *
952  * Usually this routine will succeed.  Possible errors include:
953  *  adns_s_nomemory
954  *  adns_s_rrtypeunknown
955  *  adns_s_invaliddata (*datap contained garbage)
956  * If an error occurs then no memory has been allocated,
957  * and *rrtname_r, *fmtname_r, *len_r and *data_r are undefined.
958  *
959  * There are some adns-invented data formats which are not official
960  * master file formats.  These include:
961  *
962  * Mailboxes if __qtf_mail822: these are just included as-is.
963  *
964  * Addresses (adns_rr_addr): these may be of pretty much any type.
965  * The representation is in two parts: first, a word for the address
966  * family (ie, in AF_XXX, the XXX), and then one or more items for the
967  * address itself, depending on the format.  For an IPv4 address the
968  * syntax is INET followed by the dotted quad (from inet_ntoa).
969  * Currently only IPv4 is supported.
970  *
971  * Text strings (as in adns_rr_txt) appear inside double quotes, and
972  * use \" and \\ to represent " and \, and \xHH to represent
973  * characters not in the range 32-126.
974  *
975  * Hostname with addresses (adns_rr_hostaddr): this consists of the
976  * hostname, as usual, followed by the adns_status value, as an
977  * abbreviation, and then a descriptive string (encoded as if it were
978  * a piece of text), for the address lookup, followed by zero or more
979  * addresses enclosed in ( and ).  If the result was a temporary
980  * failure, then a single ?  appears instead of the ( ).  If the
981  * result was a permanent failure then an empty pair of parentheses
982  * appears (which a space in between).  For example, one of the NS
983  * records for greenend.org.uk comes out like
984  *  ns.chiark.greenend.org.uk ok "OK" ( INET 195.224.76.132 )
985  * an MX referring to a nonexistent host might come out like:
986  *  50 sun2.nsfnet-relay.ac.uk nxdomain "No such domain" ( )
987  * and if nameserver information is not available you might get:
988  *  dns2.spong.dyn.ml.org timeout "DNS query timed out" ?
989  */
990
991 const char *adns_strerror(adns_status st);
992 const char *adns_errabbrev(adns_status st);
993 const char *adns_errtypeabbrev(adns_status st);
994 /* Like strerror but for adns_status values.  adns_errabbrev returns
995  * the abbreviation of the error - eg, for adns_s_timeout it returns
996  * "timeout".  adns_errtypeabbrev returns the abbreviation of the
997  * error class: ie, for values up to adns_s_max_XXX it will return the
998  * string XXX.  You MUST NOT call these functions with status values
999  * not returned by the same adns library.
1000  */
1001
1002 #ifdef __cplusplus
1003 } /* end of extern "C" */
1004 #endif
1005 #endif