X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=blobdiff_plain;f=src%2Fadns.h;h=070659de8c130b3fa92ff0da4e585958ccadbce6;hb=c8c7c813c5b3685f31eab503197ffa86203d54c1;hp=96eb0a5fd61073b66fcbf4290b717626237c46b8;hpb=28de64428cfdb63ad07acfcfc254907b608d5137;p=adns.git
diff --git a/src/adns.h b/src/adns.h
index 96eb0a5..070659d 100644
--- a/src/adns.h
+++ b/src/adns.h
@@ -50,7 +50,7 @@ typedef enum {
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 {
@@ -199,7 +199,7 @@ typedef enum {
/* permanent errors */
adns_s_nxdomain,
- adns_s_nodata,
+ adns_s_nodata
} adns_status;
@@ -308,6 +308,104 @@ 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);
+/* 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.
+ *
+ * Standard directives understood in resolv.conf:
+ *
+ * nameserver
+ * 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 ...
+ * 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
+ * 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 / ...
+ * 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.conf:
+ *
+ * clearnameservers
+ * Clears the list of nameservers, so that further nameserver lines
+ * start again from the beginning.
+ *
+ * include
+ * The specified file will be read.
+ *
+ * Additionally, adns will ignore lines in resolv.conf which start with a #.
+ *
+ * Standard options understood:
+ *
+ * debug
+ * Enables debugging output from the resolver, which will be written
+ * to stderr.
+ *
+ * ndots:
+ * 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
+ * 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.conf is 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,
@@ -336,6 +434,12 @@ int adns_wait(adns_state ads,
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
@@ -427,7 +531,7 @@ int adns_processexceptional(adns_state ads, int fd, const struct timeval *now);
* from, or send outgoing data via, fd. Very like _processany. If it
* returns zero then fd will no longer be readable or writeable
* (unless of course more data has arrived since). adns will _only_
- * that fd and only in the manner specified, regardless of whether
+ * use that fd and only in the manner specified, regardless of whether
* adns_if_noautosys was specified.
*
* adns_processexceptional should be called when select(2) reports an
@@ -553,7 +657,7 @@ int adns_beforepoll(adns_state ads, struct pollfd *fds, int *nfds_io, int *timeo
* in *nfds_io, and always return either 0 (if it is not interested in
* any fds) or ERANGE (if it is).
*
- * NOTE that (unless timeout_io is 0) adns may acquire additional fds
+ * NOTE that (unless now is 0) adns may acquire additional fds
* from one call to the next, so you must put adns_beforepoll in a
* loop, rather than assuming that the second call (with the buffer
* size requested by the first) will not return ERANGE.
@@ -574,9 +678,11 @@ int adns_beforepoll(adns_state ads, struct pollfd *fds, int *nfds_io, int *timeo
* adns_beforepoll will return 0 on success, and will not fail for any
* reason other than the fds buffer being too small (ERANGE).
*
- * This call will never actually do any I/O, or change the fds that
- * adns is using or the timeouts it wants; and in any case it won't
- * block.
+ * This call will never actually do any I/O. If you supply the
+ * current time it will not change the fds that adns is using or the
+ * timeouts it wants.
+ *
+ * In any case this call won't block.
*/
#define ADNS_POLLFDS_RECOMMENDED 2