X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=adns.git;a=blobdiff_plain;f=src%2Fadns.h;h=f262d478ce38898a978d5089c519dff818d4f2e8;hp=f5ffeae3b01d5feff17be51d14db22583c23e07e;hb=c227e3bcc4a3d9e4a076e19976f8b2bb153143e7;hpb=6c68a59377bb39c45cf81bbc9072126ef974b865 diff --git a/src/adns.h b/src/adns.h index f5ffeae..f262d47 100644 --- a/src/adns.h +++ b/src/adns.h @@ -5,11 +5,11 @@ /* * * This file is - * Copyright (C) 1997-1999 Ian Jackson + * Copyright (C) 1997-2000 Ian Jackson * * It is part of adns, which is - * Copyright (C) 1997-1999 Ian Jackson - * Copyright (C) 1999 Tony Finch + * Copyright (C) 1997-2000 Ian Jackson + * Copyright (C) 1999-2000 Tony Finch * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -22,13 +22,13 @@ * GNU General Public License for more details. * * - * For the benefit of certain LGPL'd `omnibus' software which provides - * a uniform interface to various things including adns, I make the - * following additional licence. I do this because the GPL would - * otherwise force either the omnibus software to be GPL'd or for the - * adns-using part to be distributed separately. + * For the benefit of certain LGPL'd `omnibus' software which + * provides a uniform interface to various things including adns, I + * make the following additional licence. I do this because the GPL + * would otherwise force either the omnibus software to be GPL'd or + * the adns-using part to be distributed separately. * - * So, you may also redistribute and/or modify adns.h (but only the + * So: you may also redistribute and/or modify adns.h (but only the * public header file adns.h and not any other part of adns) under the * terms of the GNU Library General Public License as published by the * Free Software Foundation; either version 2 of the License, or (at @@ -39,10 +39,10 @@ * applications where the whole distribution is not GPL'd, are still * likely to be in violation of the GPL. Anyone who wants to do this * should contact Ian Jackson. Please note that to avoid encouraging - * people to infringe the GPL as it applies the body of adns, I think - * that if you take advantage of the special exception to redistribute - * just adns.h under the LGPL, you should retain this paragraph in its - * place in the appropriate copyright statements. + * people to infringe the GPL as it applies to the body of adns, Ian + * thinks that if you take advantage of the special exception to + * redistribute just adns.h under the LGPL, you should retain this + * paragraph in its place in the appropriate copyright statements. * * * You should have received a copy of the GNU General Public License, @@ -56,81 +56,83 @@ #ifndef ADNS_H_INCLUDED #define ADNS_H_INCLUDED -#ifdef __cplusplus -extern "C" { /* I really dislike this - iwj. */ -#endif #include +#include +#include #include #include -#include #include #include +#ifdef __cplusplus +extern "C" { /* I really dislike this - iwj. */ +#endif + /* All struct in_addr anywhere in adns are in NETWORK byte order. */ typedef struct adns__state *adns_state; typedef struct adns__query *adns_query; typedef enum { - adns_if_noenv= 0x0001, /* do not look at environment */ - adns_if_noerrprint= 0x0002, /* never print output to stderr (_debug overrides) */ - adns_if_noserverwarn= 0x0004, /* do not warn to stderr about duff nameservers etc */ - adns_if_debug= 0x0008, /* enable all output to stderr plus debug msgs */ - adns_if_logpid= 0x0080, /* include pid in diagnostic output */ - adns_if_noautosys= 0x0010, /* do not make syscalls at every opportunity */ - adns_if_eintr= 0x0020, /* allow _wait and _synchronous to return EINTR */ - adns_if_nosigpipe= 0x0040, /* applic has SIGPIPE set to SIG_IGN, do not protect */ - adns_if_checkc_entex= 0x0100, /* do consistency checks on entry/exit to adns funcs */ - adns_if_checkc_freq= 0x0300 /* do consistency checks very frequently (slow!) */ + adns_if_noenv= 0x0001,/* do not look at environment */ + adns_if_noerrprint= 0x0002,/* never print to stderr (_debug overrides) */ + adns_if_noserverwarn=0x0004,/* do not warn to stderr about duff servers etc */ + adns_if_debug= 0x0008,/* enable all output to stderr plus debug msgs */ + adns_if_logpid= 0x0080,/* include pid in diagnostic output */ + adns_if_noautosys= 0x0010,/* do not make syscalls at every opportunity */ + adns_if_eintr= 0x0020,/* allow _wait and _synchronous to return EINTR */ + adns_if_nosigpipe= 0x0040,/* applic has SIGPIPE ignored, do not protect */ + adns_if_checkc_entex=0x0100,/* consistency checks on entry/exit to adns fns */ + adns_if_checkc_freq= 0x0300 /* consistency checks very frequently (slow!) */ } adns_initflags; typedef enum { - adns_qf_search= 0x00000001, /* use the searchlist */ - adns_qf_usevc= 0x00000002, /* use a virtual circuit (TCP connection) */ - adns_qf_owner= 0x00000004, /* fill in the owner field in the answer */ - adns_qf_quoteok_query= 0x00000010, /* allow special chars in query domain */ - adns_qf_quoteok_cname= 0x00000000, /* allow ... in CNAME we go via - now default */ - adns_qf_quoteok_anshost= 0x00000040, /* allow ... in things supposed to be hostnames */ - adns_qf_quotefail_cname= 0x00000080, /* refuse if quote-req chars in CNAME we go via */ - adns_qf_cname_loose= 0x00000100, /* allow refs to CNAMEs - without, get _s_cname */ - adns_qf_cname_forbid= 0x00000200, /* don't follow CNAMEs, instead give _s_cname */ - adns__qf_internalmask= 0x0ff00000 + adns_qf_search= 0x00000001,/* use the searchlist */ + adns_qf_usevc= 0x00000002,/* use a virtual circuit (TCP conn) */ + adns_qf_owner= 0x00000004,/* fill in the owner field in the answer */ + adns_qf_quoteok_query= 0x00000010,/* allow special chars in query domain */ + adns_qf_quoteok_cname= 0x00000000,/* ... in CNAME we go via (now default) */ + adns_qf_quoteok_anshost=0x00000040,/* ... in things supposedly hostnames */ + adns_qf_quotefail_cname=0x00000080,/* refuse if quote-req chars in CNAME we go via */ + adns_qf_cname_loose= 0x00000100,/* allow refs to CNAMEs - without, get _s_cname */ + adns_qf_cname_forbid= 0x00000200,/* don't follow CNAMEs, instead give _s_cname */ + adns__qf_internalmask= 0x0ff00000 } adns_queryflags; typedef enum { - adns__rrt_typemask= 0x0ffff, - adns__qtf_deref= 0x10000, /* dereference domains and perhaps produce extra data */ - adns__qtf_mail822= 0x20000, /* make mailboxes be in RFC822 rcpt field format */ - - adns_r_none= 0, - - adns_r_a= 1, - - adns_r_ns_raw= 2, - adns_r_ns= adns_r_ns_raw|adns__qtf_deref, - - adns_r_cname= 5, - - adns_r_soa_raw= 6, - adns_r_soa= adns_r_soa_raw|adns__qtf_mail822, - - adns_r_ptr_raw= 12, - adns_r_ptr= adns_r_ptr_raw|adns__qtf_deref, - - adns_r_hinfo= 13, - - adns_r_mx_raw= 15, - adns_r_mx= adns_r_mx_raw|adns__qtf_deref, - - adns_r_txt= 16, - - adns_r_rp_raw= 17, - adns_r_rp= adns_r_rp_raw|adns__qtf_mail822, - - adns_r_addr= adns_r_a|adns__qtf_deref - + adns__rrt_typemask=0x0ffff, + adns__qtf_deref= 0x10000, /* dereference domains; perhaps get extra data */ + adns__qtf_mail822= 0x20000, /* return mailboxes in RFC822 rcpt field fmt */ + + adns_r_none= 0, + + adns_r_a= 1, + + adns_r_ns_raw= 2, + adns_r_ns= adns_r_ns_raw|adns__qtf_deref, + + adns_r_cname= 5, + + adns_r_soa_raw= 6, + adns_r_soa= adns_r_soa_raw|adns__qtf_mail822, + + adns_r_ptr_raw= 12, /* do not mind PTR with wrong or missing A */ + adns_r_ptr= adns_r_ptr_raw|adns__qtf_deref, + + adns_r_hinfo= 13, + + adns_r_mx_raw= 15, + adns_r_mx= adns_r_mx_raw|adns__qtf_deref, + + adns_r_txt= 16, + + adns_r_rp_raw= 17, + adns_r_rp= adns_r_rp_raw|adns__qtf_mail822, + + adns_r_addr= adns_r_a|adns__qtf_deref + } adns_rrtype; /* @@ -150,12 +152,6 @@ typedef enum { * names) will be quoted, as \X if it is a printing ASCII character or * \DDD otherwise. * - * (The characters which will be unquoted are the printing 7-bit ASCII - * characters except the punctuation characters " ( ) @ ; $ \ - - * I.e. unquoted characters are alphanumerics, and the following - * punctuation characters: ! # % ^ & * - _ = + [ ] { } - * * If the query goes via a CNAME then the canonical name (ie, the * thing that the CNAME record refers to) is usually allowed to * contain any characters, which will be quoted as above. With @@ -178,72 +174,85 @@ typedef enum { * header field. The particular format used is that if the mailbox * requires quoting according to the rules in RFC822 then the * local-part is quoted in double quotes, which end at the next - * unescaped double quote. (\ is the escape char, and is doubled, and - * is used to escape only \ and ".) Otherwise the local-part is - * presented as-is. In any case this is followed by an @ and the - * domain. The domain will not contain any characters not legal in - * hostnames. adns will protect the application from local parts - * containing control characters - these appear to be legal according - * to RFC822 but are clearly a bad idea. + * unescaped double quote (\ is the escape char, and is doubled, and + * is used to escape only \ and "). If the local-part is legal + * without quoting according to RFC822, it is presented as-is. In any + * case the local-part is followed by an @ and the domain. The domain + * will not contain any characters not legal in hostnames. + * + * Unquoted local-parts may contain any printing 7-bit ASCII + * except the punctuation characters ( ) < > @ , ; : \ " [ ] + * I.e. they may contain alphanumerics, and the following + * punctuation characters: ! # % ^ & * - _ = + { } . + * + * adns will reject local parts containing control characters (byte + * values 0-31, 127-159, and 255) - these appear to be legal according + * to RFC822 (at least 0-127) but are clearly a bad idea. RFC1035 + * syntax does not make any distinction between a single RFC822 + * quoted-string containing full stops, and a series of quoted-strings + * separated by full stops; adns will return anything that isn't all + * valid atoms as a single quoted-string. RFC822 does not allow + * high-bit-set characters at all, but adns does allow them in + * local-parts, treating them as needing quoting. * * If you ask for the domain with _raw then _no_ checking is done * (even on the host part, regardless of adns_qf_quoteok_anshost), and * you just get the domain name in master file format. * * If no mailbox is supplied the returned string will be `.' in either - * caswe. + * case. */ typedef enum { - adns_s_ok, - - /* locally induced errors */ - adns_s_nomemory, - adns_s_unknownrrtype, - adns_s_systemfail, - - adns_s_max_localfail= 29, - - /* remotely induced errors, detected locally */ - adns_s_timeout, - adns_s_allservfail, - adns_s_norecurse, - adns_s_invalidresponse, - adns_s_unknownformat, - - adns_s_max_remotefail= 59, - - /* remotely induced errors, reported by remote server to us */ - adns_s_rcodeservfail, - adns_s_rcodeformaterror, - adns_s_rcodenotimplemented, - adns_s_rcoderefused, - adns_s_rcodeunknown, - - adns_s_max_tempfail= 99, - - /* remote configuration errors */ - adns_s_inconsistent, /* PTR gives domain whose A does not exist and match */ - adns_s_prohibitedcname, /* CNAME found where eg A expected (not if _qf_loosecname) */ - adns_s_answerdomaininvalid, - adns_s_answerdomaintoolong, - adns_s_invaliddata, - - adns_s_max_misconfig= 199, - - /* permanent problems with the query */ - adns_s_querydomainwrong, - adns_s_querydomaininvalid, - adns_s_querydomaintoolong, - - adns_s_max_misquery= 299, - - /* permanent errors */ - adns_s_nxdomain, - adns_s_nodata, - - adns_s_max_permfail= 499 - + adns_s_ok, + + /* locally induced errors */ + adns_s_nomemory, + adns_s_unknownrrtype, + adns_s_systemfail, + + adns_s_max_localfail= 29, + + /* remotely induced errors, detected locally */ + adns_s_timeout, + adns_s_allservfail, + adns_s_norecurse, + adns_s_invalidresponse, + adns_s_unknownformat, + + adns_s_max_remotefail= 59, + + /* remotely induced errors, reported by remote server to us */ + adns_s_rcodeservfail, + adns_s_rcodeformaterror, + adns_s_rcodenotimplemented, + adns_s_rcoderefused, + adns_s_rcodeunknown, + + adns_s_max_tempfail= 99, + + /* remote configuration errors */ + adns_s_inconsistent, /* PTR gives domain whose A does not exist and match */ + adns_s_prohibitedcname, /* CNAME, but eg A expected (not if _qf_loosecname) */ + adns_s_answerdomaininvalid, + adns_s_answerdomaintoolong, + adns_s_invaliddata, + + adns_s_max_misconfig= 199, + + /* permanent problems with the query */ + adns_s_querydomainwrong, + adns_s_querydomaininvalid, + adns_s_querydomaintoolong, + + adns_s_max_misquery= 299, + + /* permanent errors */ + adns_s_nxdomain, + adns_s_nodata, + + adns_s_max_permfail= 499 + } adns_status; typedef struct { @@ -271,10 +280,11 @@ typedef struct { } adns_rr_inthostaddr; typedef struct { - /* Used both for mx_raw, in which case i is the preference and str the domain, - * and for txt, in which case each entry has i for the `text' length, - * and str for the data (which will have had an extra nul appended - * so that if it was plain text it is now a null-terminated string). + /* Used both for mx_raw, in which case i is the preference and str + * the domain, and for txt, in which case each entry has i for the + * `text' length, and str for the data (which will have had an extra + * nul appended so that if it was plain text it is now a + * null-terminated string). */ int i; char *str; @@ -292,23 +302,23 @@ typedef struct { typedef struct { adns_status status; char *cname; /* always NULL if query was for CNAME records */ - char *owner; /* only set if requested in query flags, and may be 0 on error anyway */ + char *owner; /* only set if req'd in query flags; maybe 0 on error anyway */ adns_rrtype type; /* guaranteed to be same as in query */ - time_t expires; /* expiry time, defined only if _s_ok, nxdomain or nodata. NOT TTL! */ + time_t expires;/*abs time. def only if _s_ok, nxdomain or nodata. NOT TTL!*/ int nrrs, rrsz; /* nrrs is 0 if an error occurs */ union { void *untyped; unsigned char *bytes; - char *(*str); /* ns_raw, cname, ptr, ptr_raw */ - adns_rr_intstr *(*manyistr); /* txt (list of strings ends with i=-1, str=0) */ - adns_rr_addr *addr; /* addr */ - struct in_addr *inaddr; /* a */ - adns_rr_hostaddr *hostaddr; /* ns */ - adns_rr_intstrpair *intstrpair; /* hinfo */ - adns_rr_strpair *strpair; /* rp, rp_raw */ - adns_rr_inthostaddr *inthostaddr; /* mx */ - adns_rr_intstr *intstr; /* mx_raw */ - adns_rr_soa *soa; /* soa, soa_raw */ + char *(*str); /* ns_raw, cname, ptr, ptr_raw */ + adns_rr_intstr *(*manyistr); /* txt (list strs ends with i=-1, str=0)*/ + adns_rr_addr *addr; /* addr */ + struct in_addr *inaddr; /* a */ + adns_rr_hostaddr *hostaddr; /* ns */ + adns_rr_intstrpair *intstrpair; /* hinfo */ + adns_rr_strpair *strpair; /* rp, rp_raw */ + adns_rr_inthostaddr *inthostaddr;/* mx */ + adns_rr_intstr *intstr; /* mx_raw */ + adns_rr_soa *soa; /* soa, soa_raw */ } rrs; } adns_answer; @@ -351,6 +361,19 @@ int adns_init(adns_state *newstate_r, adns_initflags flags, int adns_init_strcfg(adns_state *newstate_r, adns_initflags flags, FILE *diagfile /*0=>discard*/, const char *configtext); +typedef void adns_logcallbackfn(adns_state ads, void *logfndata, + const char *fmt, va_list al); + /* Will be called perhaps several times for each message; when the + * message is complete, the string implied by fmt and al will end in + * a newline. Log messages start with `adns debug:' or `adns + * warning:' or `adns:' (for errors), or `adns debug [PID]:' + * etc. if adns_if_logpid is set. */ + +int adns_init_logfn(adns_state *newstate_r, adns_initflags flags, + const char *configtext /*0=>use default config files*/, + adns_logcallbackfn *logfn /*0=>logfndata is a FILE* */, + void *logfndata /*0 with logfn==0 => discard*/); + /* Configuration: * adns_init reads /etc/resolv.conf, which is expected to be (broadly * speaking) in the format expected by libresolv, and then @@ -663,10 +686,10 @@ void adns_beforeselect(adns_state ads, int *maxfd, fd_set *readfds, * for adns_firsttimeout. readfds, writefds, exceptfds and maxfd_io may * not be 0. * - * If now is not 0 then this will never actually do any I/O, or change - * the fds that adns is using or the timeouts it wants. In any case - * it won't block, and it will set the timeout to zero if a query - * finishes in _beforeselect. + * If tv_mod is 0 on entry then this will never actually do any I/O, + * or change the fds that adns is using or the timeouts it wants. In + * any case it won't block, and it will set the timeout to zero if a + * query finishes in _beforeselect. */ void adns_afterselect(adns_state ads, int maxfd, const fd_set *readfds, @@ -703,7 +726,8 @@ struct pollfd; * entrypoints will not be defined in libadns. Sorry ! */ -int adns_beforepoll(adns_state ads, struct pollfd *fds, int *nfds_io, int *timeout_io, +int adns_beforepoll(adns_state ads, struct pollfd *fds, + int *nfds_io, int *timeout_io, const struct timeval *now); /* Finds out which fd's adns is interested in, and when it would like * to be able to time things out. This is in a form suitable for use