* - 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
* 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.
*
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software Foundation,
+ * 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.
+ *
+ * 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$
*/
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_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 */
* 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
/* permanent errors */
adns_s_nxdomain,
- adns_s_nodata
+ adns_s_nodata,
+
+ adns_s_max_permfail= 499
} adns_status;
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 */
* 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.
/* 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
* 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
* 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:
*
* 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.
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,
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;
* adns_submit 2
* adns_submit 3
* adns_wait 1
- * adns_check 3 -> EWOULDBLOCK
+ * adns_check 3 -> EAGAIN
* adns_wait 2
* adns_wait 3
* ....
* 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.
*/
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
* 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 )
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.
*/
~ianmdlvl / adns.git / blobdiff