X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=adns.git;a=blobdiff_plain;f=src%2Fadns.h;h=343501d109e9435fe67f131d6e1c8bcee60084b6;hp=eed7f79c0a37f9dac9b297478041f054447b367d;hb=06f8e611d7be5a4c745396f423ab5cd6cdc6bfdd;hpb=0a106d94b0b562568297f2bc7e9a39a709574010 diff --git a/src/adns.h b/src/adns.h index eed7f79..343501d 100644 --- a/src/adns.h +++ b/src/adns.h @@ -3,7 +3,13 @@ * - 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 + * + * It is part of adns, which is + * Copyright (C) 1997-1999 Ian Jackson + * Copyright (C) 1999 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 @@ -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. + * + * + * 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. * + * * $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_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_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_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 */ @@ -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 " - * 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 @@ -200,6 +241,8 @@ typedef enum { /* permanent errors */ adns_s_nxdomain, adns_s_nodata, + + adns_s_max_permfail= 499 } adns_status; @@ -249,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 */ @@ -288,9 +331,9 @@ typedef struct { * 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 - * 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. @@ -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); +/* 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
+ * 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[-adns].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[-adns].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[-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, @@ -326,6 +469,8 @@ int adns_submit(adns_state ads, 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, @@ -362,7 +507,22 @@ int adns_submit_reverse(adns_state ads, 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 + * . + * 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; @@ -401,7 +561,7 @@ void adns_checkconsistency(adns_state ads, adns_query qu); * adns_submit 2 * adns_submit 3 * adns_wait 1 - * adns_check 3 -> EWOULDBLOCK + * adns_check 3 -> EAGAIN * 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. * - * 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. */ @@ -607,7 +767,6 @@ adns_status adns_rr_info(adns_rrtype type, 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 @@ -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 - * 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 ) @@ -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_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 - * "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. */