X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=src%2Fadns.h;h=f5ffeae3b01d5feff17be51d14db22583c23e07e;hb=626f869531a241dd8f187afb392a3151caf9a728;hp=29d7ede611f943bd931d93ad2a65b0910151d69b;hpb=d7449548b74b994a0d7390c5f153f40f02b46105;p=adns.git

diff --git a/src/adns.h b/src/adns.h
index 29d7ede..f5ffeae 100644
--- a/src/adns.h
+++ b/src/adns.h
@@ -78,6 +78,7 @@ typedef enum {
   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 */
@@ -89,7 +90,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 */
@@ -141,11 +142,19 @@ 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.
+ *
+ * (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
@@ -283,7 +292,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 */
@@ -344,12 +353,13 @@ int adns_init_strcfg(adns_state *newstate_r, adns_initflags flags,
 
 /* 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 <address>
  *   Must be followed by the IP address of a nameserver.  Several
@@ -382,7 +392,7 @@ int adns_init_strcfg(adns_state *newstate_r, adns_initflags flags,
  *   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
@@ -391,7 +401,8 @@ int adns_init_strcfg(adns_state *newstate_r, adns_initflags flags,
  *  include <filename>
  *   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:
  *
@@ -420,7 +431,7 @@ int adns_init_strcfg(adns_state *newstate_r, adns_initflags flags,
  * 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.
@@ -500,6 +511,19 @@ int adns_submit_reverse(adns_state ads,
  * 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
+ *   <reversed-address>.<zone>
+ * 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.
@@ -639,9 +663,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,
@@ -786,9 +811,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 )