adns.h

adns for unix/linux, adns-1.3.tar.gz

  int i;
  adns_rr_hostaddr ha;
} 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).
   */
  int i;
  char *str;
} adns_rr_intstr;

typedef struct {
  adns_rr_intstr array[2];
} adns_rr_intstrpair;

typedef struct {
  char *mname, *rname;
  unsigned long serial, refresh, retry, expire, minimum;
} adns_rr_soa;

typedef struct {
  int priority, weight, port;
  char *host;
} adns_rr_srvraw;

typedef struct {
  int priority, weight, port;
  adns_rr_hostaddr ha;
} adns_rr_srvha;

typedef struct {
  int len;
  unsigned char *data;
} adns_rr_byteblock;

typedef struct {
  adns_status status;
  char *cname; /* always NULL if query was for CNAME records */
  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;/*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 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 */
    adns_rr_srvraw *srvraw;          /* srv_raw */
    adns_rr_srvha *srvha;/* srv */
    adns_rr_byteblock *byteblock;    /* ...|unknown */
  } rrs;
} adns_answer;

/* Memory management:
 *  adns_state and adns_query are actually pointers to malloc'd state;
 *  On submission questions are copied, including the owner domain;
 *  Answers are malloc'd as a single piece of memory; pointers in the
 *  answer struct point into further memory in the answer.
 * query_io:
 *  Must always be non-null pointer;
 *  If *query_io is 0 to start with then any query may be returned;
 *  If *query_io is !0 adns_query then only that query may be returned.
 *  If the call is successful, *query_io, *answer_r, and *context_r
 *  will all be set.
 * Errors:
 *  Return values are 0 or an errno value.
 *
 *  For _init, _init_strcfg, _submit and _synchronous, system errors
 *  (eg, failure to create sockets, malloc failure, etc.) return errno
 *  values.  EINVAL from _init et al means the configuration file
 *  is erroneous and cannot be parsed.
 * 
 *  For _wait and _check failures are reported in the answer
 *  structure, and only 0, ESRCH or (for _check) EAGAIN is
 *  returned: if no (appropriate) requests are done adns_check returns
 *  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.
 *
 *  All other errors (nameserver failure, timed out connections, &c)
 *  are returned in the status field of the answer.  After a
 *  successful _wait or _check, if status is nonzero then nrrs will be
 *  0, otherwise it will be >0.  type will always be the type
 *  requested.
 */

int adns_init(adns_state *newstate_r, adns_initflags flags,
	      FILE *diagfile /*0=>stderr*/);

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
 *  /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,
		     adns_queryflags flags,
		     adns_answer **answer_r);

/* NB: if you set adns_if_noautosys then _submit and _check do not
 * make any system calls; you must use some of the asynch-io event
 * processing functions to actually get things to happen.
 */

int adns_submit(adns_state ads,
		const char *owner,
		adns_rrtype type,
		adns_queryflags flags,
		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,
	       void **context_r);

int adns_wait(adns_state ads,
	      adns_query *query_io,
	      adns_answer **answer_r,
	      void **context_r);

/* same as adns_wait but uses poll(2) internally */
int adns_wait_poll(adns_state ads,
		   adns_query *query_io,
		   adns_answer **answer_r,
		   void **context_r);

void adns_cancel(adns_query query);

/* The adns_query you get back from _submit is valid (ie, can be
 * legitimately passed into adns functions) until it is returned by
 * adns_check or adns_wait, or passed to adns_cancel.  After that it
 * must not be used.  You can rely on it not being reused until the
 * first adns_submit or _transact call using the same adns_state after
 * it became invalid, so you may compare it for equality with other
 * query handles until you next call _query or _transact.
 *
 * _submit and _synchronous return ENOSYS if they don't understand the
 * query type.
 */

int adns_submit_reverse(adns_state ads,
			const struct sockaddr *addr,
			adns_rrtype type,
			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
 *   <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.
 */


void adns_forallqueries_begin(adns_state ads);
adns_query adns_forallqueries_next(adns_state ads, void **context_r);
/* Iterator functions, which you can use to loop over the outstanding
 * (submitted but not yet successfuly checked/waited) queries.
 *
 * You can only have one iteration going at once.  You may call _begin
 * at any time; after that, an iteration will be in progress.  You may