X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;ds=sidebyside;f=src%2Fadns.h;h=1b14ef959656420305ca769ea14c8236a31a0ed1;hb=07b2653a2a362473777e4d3dbd7d2b810886c0ce;hp=343501d109e9435fe67f131d6e1c8bcee60084b6;hpb=06f8e611d7be5a4c745396f423ab5cd6cdc6bfdd;p=adns.git diff --git a/src/adns.h b/src/adns.h index 343501d..1b14ef9 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,82 @@ #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 +#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, + 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 +151,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 +173,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 +279,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 +301,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; @@ -663,9 +672,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. + * 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. */ void adns_afterselect(adns_state ads, int maxfd, const fd_set *readfds, @@ -702,7 +712,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