+ * Documented that adns_rr_info _rr_hostaddr ( ) for address list

[adns.git] / src / adns.h

diff --git a/src/adns.h b/src/adns.h
index eed7f79c0a37f9dac9b297478041f054447b367d..343501d109e9435fe67f131d6e1c8bcee60084b6 100644 (file)
--- a/src/adns.h
+++ b/src/adns.h
@@ -3,7 +3,13 @@
  * - adns user-visible API (single-threaded, without any locking)
  */
 /*
  * - adns user-visible API (single-threaded, without any locking)
  */
 /*

- *  This file is part of adns, which is Copyright (C) 1997-1999 Ian Jackson
+ *
+ *  This file is
+ *    Copyright (C) 1997-1999 Ian Jackson <ian@davenant.greenend.org.uk>
+ *
+ *  It is part of adns, which is
+ *    Copyright (C) 1997-1999 Ian Jackson <ian@davenant.greenend.org.uk>
+ *    Copyright (C) 1999 Tony Finch <dot@dotat.at>

  *  
  *  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
  *  
  *  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


@@ -14,11 +20,37 @@
  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  *  GNU General Public License for more details.
  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  *  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.
+ *  
+ *  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
+ *  your option) any later version.

  *  
  *  

- *  You should have received a copy of the GNU General Public License
- *  along with this program; if not, write to the Free Software Foundation,
+ *  Note that adns itself is GPL'd.  Authors of adns-using applications
+ *  with GPL-incompatible licences, and people who distribute adns with
+ *  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.
+ *
+ *
+ *  You should have received a copy of the GNU General Public License,
+ *  or the GNU Library General Public License, as appropriate, along
+ *  with this program; if not, write to the Free Software Foundation,

  *  Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  *
  *  Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  *

+ *

  *  $Id$
  */
 
  *  $Id$
  */
 


@@ -46,18 +78,19 @@ 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_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_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_checkc_freq=  0x0300  /* do 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_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 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 */
   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 */


@@ -109,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 "
  * 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
  *
  * If the query goes via a CNAME then the canonical name (ie, the
  * thing that the CNAME record refers to) is usually allowed to


@@ -200,6 +241,8 @@ typedef enum {
   /* permanent errors */
   adns_s_nxdomain,
   adns_s_nodata,
   /* permanent errors */
   adns_s_nxdomain,
   adns_s_nodata,

+
+  adns_s_max_permfail= 499

   
 } adns_status;
 
   
 } adns_status;
 


@@ -249,7 +292,7 @@ typedef struct {
 typedef struct {
   adns_status status;
   char *cname; /* always NULL if query was for CNAME records */
 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 */
   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 */


@@ -288,9 +331,9 @@ typedef struct {
  *  values.
  * 
  *  For _wait and _check failures are reported in the answer
  *  values.
  * 
  *  For _wait and _check failures are reported in the answer

- *  structure, and only 0, ESRCH or (for _check) EWOULDBLOCK is
+ *  structure, and only 0, ESRCH or (for _check) EAGAIN is

  *  returned: if no (appropriate) requests are done adns_check returns
  *  returned: if no (appropriate) requests are done adns_check returns

- *  EWOULDBLOCK; if no (appropriate) requests are outstanding both
+ *  EAGAIN; if no (appropriate) requests are outstanding both

  *  adns_query and adns_wait return ESRCH.
  *
  *  Additionally, _wait can return EINTR if you set adns_if_eintr.
  *  adns_query and adns_wait return ESRCH.
  *
  *  Additionally, _wait can return EINTR if you set adns_if_eintr.


@@ -308,6 +351,106 @@ 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);
 
 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, 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[-adns].conf:
+ * 
+ *  nameserver <address>
+ *   Must be followed by the IP address of a nameserver.  Several
+ *   nameservers may be specified, and they will be tried in the order
+ *   found.  There is a compiled in limit, currently 5, on the number
+ *   of nameservers.  (libresolv supports only 3 nameservers.)
+ *
+ *  search <domain> ...
+ *   Specifies the search list for queries which specify
+ *   adns_qf_search.  This is a list of domains to append to the query
+ *   domain.  The query domain will be tried as-is either before all
+ *   of these or after them, depending on the ndots option setting
+ *   (see below).
+ *
+ *  domain <domain>
+ *   This is present only for backward compatibility with obsolete
+ *   versions of libresolv.  It should not be used, and is interpreted
+ *   by adns as if it were `search' - note that this is subtly
+ *   different to libresolv's interpretation of this directive.
+ *
+ *  sortlist <addr>/<mask> ...
+ *   Should be followed by a sequence of IP-address and netmask pairs,
+ *   separated by spaces.  They may be specified as
+ *   eg. 172.30.206.0/24 or 172.30.206.0/255.255.255.0.  Currently up
+ *   to 15 pairs may be specified (but note that libresolv only
+ *   supports up to 10).
+ *
+ *  options
+ *   Should followed by one or more options, separated by spaces.
+ *   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[-adns].conf:
+ *
+ *  clearnameservers
+ *   Clears the list of nameservers, so that further nameserver lines
+ *   start again from the beginning.
+ *
+ *  include <filename>
+ *   The specified file will be read.
+ *
+ * Additionally, adns will ignore lines in resolv[-adns].conf which
+ * start with a #.
+ *
+ * Standard options understood:
+ *
+ *  debug
+ *   Enables debugging output from the resolver, which will be written
+ *   to stderr.
+ *
+ *  ndots:<count>
+ *   Affects whether queries with adns_qf_search will be tried first
+ *   without adding domains from the searchlist, or whether the bare
+ *   query domain will be tried last.  Queries which contain at least
+ *   <count> dots will be tried bare first.  The default is 1.
+ *
+ * Non-standard options understood:
+ *
+ *  adns_checkc:none
+ *  adns_checkc:entex
+ *  adns_checkc:freq
+ *   Changes the consistency checking frequency; this overrides the
+ *   setting of adns_if_check_entex, adns_if_check_freq, or neither,
+ *   in the flags passed to adns_init.
+ * 
+ * There are a number of environment variables which can modify the
+ * behaviour of adns.  They take effect only if adns_init is used, and
+ * the caller of adns_init can disable them using adns_if_noenv.  In
+ * 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[-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.
+ *
+ *  RES_CONF_TEXT, ADNS_RES_CONF_TEXT
+ *   A string in the format of resolv.conf.
+ *
+ *  RES_OPTIONS, ADNS_RES_OPTIONS
+ *   These are parsed as if they appeared in the `options' line of a
+ *   resolv.conf.  In addition to being parsed at this point in the
+ *   sequence, they are also parsed at the very beginning before
+ *   resolv.conf or any other environment variables are read, so that
+ *   any debug option can affect the processing of the configuration.
+ *
+ *  LOCALDOMAIN, ADNS_LOCALDOMAIN
+ *   These are interpreted as if their contents appeared in a `search'
+ *   line in resolv.conf.
+ */
+

 int adns_synchronous(adns_state ads,
                     const char *owner,
                     adns_rrtype type,
 int adns_synchronous(adns_state ads,
                     const char *owner,
                     adns_rrtype type,


@@ -326,6 +469,8 @@ int adns_submit(adns_state ads,
                void *context,
                adns_query *query_r);
 
                void *context,
                adns_query *query_r);
 

+/* The owner should be quoted in master file format. */
+

 int adns_check(adns_state ads,
               adns_query *query_io,
               adns_answer **answer_r,
 int adns_check(adns_state ads,
               adns_query *query_io,
               adns_answer **answer_r,


@@ -362,7 +507,22 @@ int adns_submit_reverse(adns_state ads,
                        adns_queryflags flags,
                        void *context,
                        adns_query *query_r);
                        adns_queryflags flags,
                        void *context,
                        adns_query *query_r);

-/* type must be _r_ptr or _r_ptr_raw.  _qf_search is ignored. */
+/* 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
+ *   <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;
 
 void adns_finish(adns_state ads);
 /* You may call this even if you have queries outstanding;


@@ -401,7 +561,7 @@ void adns_checkconsistency(adns_state ads, adns_query qu);
  *  adns_submit 2
  *  adns_submit 3
  *  adns_wait 1
  *  adns_submit 2
  *  adns_submit 3
  *  adns_wait 1

- *  adns_check 3 -> EWOULDBLOCK
+ *  adns_check 3 -> EAGAIN

  *  adns_wait 2
  *  adns_wait 3
  *  ....
  *  adns_wait 2
  *  adns_wait 3
  *  ....


@@ -503,7 +663,7 @@ void adns_beforeselect(adns_state ads, int *maxfd, fd_set *readfds,
  * for adns_firsttimeout.  readfds, writefds, exceptfds and maxfd_io may
  * not be 0.
  *
  * 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
+ * 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.
  */
  * change the fds that adns is using or the timeouts it wants.  In any
  * case it won't block.
  */


@@ -607,7 +767,6 @@ adns_status adns_rr_info(adns_rrtype type,
                         int *len_r,
                         const void *datap, char **data_r);
 /*
                         int *len_r,
                         const void *datap, char **data_r);
 /*

-  

  * Get information about a query type, or convert reply data to a
  * textual form.  type must be specified, and the official name of the
  * corresponding RR type will be returned in *rrtname_r, and
  * Get information about a query type, or convert reply data to a
  * textual form.  type must be specified, and the official name of the
  * corresponding RR type will be returned in *rrtname_r, and


@@ -651,9 +810,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
  * 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
  * 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 )
  * 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 )


@@ -665,9 +824,12 @@ adns_status adns_rr_info(adns_rrtype type,
 
 const char *adns_strerror(adns_status st);
 const char *adns_errabbrev(adns_status st);
 
 const char *adns_strerror(adns_status st);
 const char *adns_errabbrev(adns_status st);

+const char *adns_errtypeabbrev(adns_status st);

 /* Like strerror but for adns_status values.  adns_errabbrev returns
  * the abbreviation of the error - eg, for adns_s_timeout it returns
 /* Like strerror but for adns_status values.  adns_errabbrev returns
  * the abbreviation of the error - eg, for adns_s_timeout it returns

- * "timeout".  You MUST NOT call these functions with status values
+ * "timeout".  adns_errtypeabbrev returns the abbreviation of the
+ * error class: ie, for values up to adns_s_max_XXX it will return the
+ * string XXX.  You MUST NOT call these functions with status values

  * not returned by the same adns library.
  */
 
  * not returned by the same adns library.
  */