X-Git-Url: https://git.distorted.org.uk/~mdw/adns/blobdiff_plain/a122e99d41be2e0f03311cf41e3eda4935238056..cebf6f2bc03f8c80a41e762b0940ad301dfc7a2b:/src/adns.h diff --git a/src/adns.h b/src/adns.h index 0a2b6c8..4297fca 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, @@ -51,23 +51,24 @@ * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. * * - * $Id: adns.h,v 1.71 1999/10/15 16:55:00 ian Exp $ + * $Id: adns.h,v 1.84 2002/11/24 17:23:01 ian Exp $ */ #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; @@ -90,7 +91,7 @@ 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 quote-requiring chars in query domain */ + 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 */ @@ -142,11 +143,13 @@ typedef enum { * In queries _with_ qf_quoteok_*, domains in the query or response * may contain any characters, quoted according to RFC1035 5.1. On * input to adns, the char* is a pointer to the interior of a " - * delimited string, except that " may appear in it, and on output, - * the char* is a pointer to a string which would be legal either - * inside or outside " delimiters, and any characters not usually - * legal in domain names will be quoted as \X (if the character is - * 33-126 except \ and ") or \DDD. + * delimited string, except that " may appear in it unquoted. On + * output, the char* is a pointer to a string which would be legal + * either inside or outside " delimiters; any character which isn't + * legal in a hostname (ie alphanumeric or hyphen) or one of _ / + + * (the three other punctuation characters commonly abused in domain + * names) will be quoted, as \X if it is a printing ASCII character or + * \DDD otherwise. * * If the query goes via a CNAME then the canonical name (ie, the * thing that the CNAME record refers to) is usually allowed to @@ -170,20 +173,33 @@ 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 { @@ -284,7 +300,7 @@ 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 */ + char *owner; /* only set if requested in query flags, and may be 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! */ int nrrs, rrsz; /* nrrs is 0 if an error occurs */ @@ -337,20 +353,21 @@ typedef struct { * requested. */ -int adns_init(adns_state *newstate_r, int flags /*adns_initflags*/, +int adns_init(adns_state *newstate_r, adns_initflags flags, FILE *diagfile /*0=>stderr*/); -int adns_init_strcfg(adns_state *newstate_r, int flags /*adns_initflags*/, +int adns_init_strcfg(adns_state *newstate_r, adns_initflags flags, FILE *diagfile /*0=>discard*/, const char *configtext); /* Configuration: * adns_init reads /etc/resolv.conf, which is expected to be (broadly - * speaking) in the format expected by libresolv. adns_init_strcfg - * is instead passed a string which is interpreted as if it were the - * contents of resolv.conf. In general, configuration which is set - * later overrides any that is set earlier. + * speaking) in the format expected by libresolv, and then + * /etc/resolv-adns.conf if it exists. adns_init_strcfg is instead + * passed a string which is interpreted as if it were the contents of + * resolv.conf or resolv-adns.conf. In general, configuration which + * is set later overrides any that is set earlier. * - * Standard directives understood in resolv.conf: + * Standard directives understood in resolv[-adns].conf: * * nameserver
* Must be followed by the IP address of a nameserver. Several @@ -383,7 +400,7 @@ int adns_init_strcfg(adns_state *newstate_r, int flags /*adns_initflags*/, * Each option consists of an option name, followed by optionally * a colon and a value. Options are listed below. * - * Non-standard directives understood in resolv.conf: + * Non-standard directives understood in resolv[-adns].conf: * * clearnameservers * Clears the list of nameservers, so that further nameserver lines @@ -392,7 +409,8 @@ int adns_init_strcfg(adns_state *newstate_r, int flags /*adns_initflags*/, * include * The specified file will be read. * - * Additionally, adns will ignore lines in resolv.conf which start with a #. + * Additionally, adns will ignore lines in resolv[-adns].conf which + * start with a #. * * Standard options understood: * @@ -421,7 +439,7 @@ int adns_init_strcfg(adns_state *newstate_r, int flags /*adns_initflags*/, * each case there is both a FOO and an ADNS_FOO; the latter is * interpreted later so that it can override the former. Unless * otherwise stated, environment variables are interpreted after - * resolv.conf is read, in the order they are listed here. + * resolv[-adns].conf are read, in the order they are listed here. * * RES_CONF, ADNS_RES_CONF * A filename, whose contets are in the format of resolv.conf. @@ -444,7 +462,7 @@ int adns_init_strcfg(adns_state *newstate_r, int flags /*adns_initflags*/, int adns_synchronous(adns_state ads, const char *owner, adns_rrtype type, - int flags /*adns_queryflags*/, + adns_queryflags flags, adns_answer **answer_r); /* NB: if you set adns_if_noautosys then _submit and _check do not @@ -455,7 +473,7 @@ int adns_synchronous(adns_state ads, int adns_submit(adns_state ads, const char *owner, adns_rrtype type, - int flags /*adns_queryflags*/, + adns_queryflags flags, void *context, adns_query *query_r); @@ -494,13 +512,26 @@ void adns_cancel(adns_query query); int adns_submit_reverse(adns_state ads, const struct sockaddr *addr, adns_rrtype type, - int flags /*adns_queryflags*/, + adns_queryflags flags, void *context, adns_query *query_r); /* type must be _r_ptr or _r_ptr_raw. _qf_search is ignored. * addr->sa_family must be AF_INET or you get ENOSYS. */ +int adns_submit_reverse_any(adns_state ads, + const struct sockaddr *addr, + const char *rzone, + adns_rrtype type, + adns_queryflags flags, + void *context, + adns_query *query_r); +/* For RBL-style reverse `zone's; look up + * . + * Any type is allowed. _qf_search is ignored. + * addr->sa_family must be AF_INET or you get ENOSYS. + */ + void adns_finish(adns_state ads); /* You may call this even if you have queries outstanding; * they will be cancelled. @@ -640,9 +671,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, @@ -787,9 +819,9 @@ adns_status adns_rr_info(adns_rrtype type, * hostname, as usual, followed by the adns_status value, as an * abbreviation, and then a descriptive string (encoded as if it were * a piece of text), for the address lookup, followed by zero or more - * addresses enclosed in ( and ). If the result was a permanent + * addresses enclosed in ( and ). If the result was a temporary * failure, then a single ? appears instead of the ( ). If the - * result was a temporary failure then an empty pair of parentheses + * result was a permanent failure then an empty pair of parentheses * appears (which a space in between). For example, one of the NS * records for greenend.org.uk comes out like * ns.chiark.greenend.org.uk ok "OK" ( INET 195.224.76.132 )