[adns] / README.html

<html><head><title>adns - advanced, alternative, asynchronous resolver</title>
<!--
  Note: this file is maintained in Ian Jackson's private CVS.

  It is served on the GNU site and also from my own system, under the
  URL http://www.chiark.greenend.org.uk/adns/ Please ensure that all
  links continine to be correct both for www.gnu.org and chiark.

  $Id$
  -->   
<link rev="made" href="mailto:adns-maint@chiark.greenend.org.uk">
</head>
<body>
<h1>GNU adns</h1>

<strong>Advanced, easy to use, asynchronous-capable DNS client
library and utilities.</strong>

<p>

adns is a resolver library for C (and C++) programs, and a collection
of useful DNS resolver utilities.  In contrast with the existing
interfaces, gethostbyname et al and libresolv, it has the following
features:

<ul>

<li>It is reasonably easy to use for simple programs which just want
to translate names to addresses, look up MX records, etc.

<li>It can be used in an asynchronous, non-blocking, manner.  Many
queries can be handled simultaneously.

<li>Responses are decoded automatically into a natural representation
for a C program - there is no need to deal with DNS packet formats.

<li>Sanity checking (eg, name syntax checking, reverse/forward
correspondence, CNAME pointing to CNAME) is performed automatically.

<li>Time-to-live, CNAME and other similar information is returned in
an easy-to-use form, without getting in the way.

<li>There is no global state in the library; resolver state is an
opaque data structure which the client creates explicitly.  A program
can have several instances of the resolver.

<li>Errors are reported to the application in a way that distinguishes
the various causes of failure properly.

<li>Understands conventional resolv.conf, but this can overridden by
environment variables.

<li>Flexibility.  For example, the application can tell adns to:
ignore environment variables (for setuid programs), disable hostname
syntax sanity checks to return arbitrary data, override or ignore
resolv.conf in favour of supplied configuration, etc.

<li>Believed to be correct !  For example, will correctly back off to
TCP in case of long replies or queries, or to other nameservers if
several are available.  It has sensible handling of bad responses etc.

</ul>

<h2>DNS utility programs</h2>

adns also comes with a number of utility programs for use from the
command line and in scripts:

<ul>

<li><code>adnslogres</code> is a much faster version of Apache's
logresolv program.

<li><code>adnsresfilter</code> is a filter which copies its input to
its output, replacing IP addresses by the corresponding names, without
unduly delaying the output.  For example, you can usefully pipe the
output of netstat -n, tcpdump -ln, and the like, into it.

<li><code>adnshost</code> is a general-purpose DNS lookup utility
which can be used easily in from the command line and from shell
scripts to do simple lookups.  In a more advanced mode it can be used
as a general-purpose DNS helper program for scripting languages which
can invoke and communicate with subprocesses.  See the
<A href="http://www.chiark.greenend.org.uk/~ian/adns/usage/adnsresfilter_usage.text">usage
message</A> for a summary of its capabilities.

</ul>

<h2>Technical note</h2>

adns requires a real nameserver like
<A href="http://www.isc.org/view.cgi?/products/BIND/index.phtml">BIND</A>
or
<A href="http://www.dents.org/">Dents</A> running on
the same system or a nearby one, which must be willing to provide
`recursive service'.  I.e., adns is a `stub resolver'.  All properly
configured UN*X and GNU systems will already have such nameserver(s);
they are usually listed in /etc/resolv.conf.

<h2>Documentation</h2>

I'm afraid there is no manual yet.  However, competent C programmers
should be able to use the library based on the
<A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">commented
adns.h header file</A>, and the usage messages for the programs should
be sufficient.

<h2>Feedback</h2>

I'd be pleased if you would let me know if you're using my library in
your project, and what you think of it.

<p>

If you are subscribed to <code>adns-discuss</code> please send
feedback, including bug reports, there; otherwise send mail to
<code>adns-bugreports@chiark.greenend.org.uk</code>.  If you'd prefer
that your message wasn't forwarded to the <code>adns-bugreports</code>
list, send it to <code>adns-maint@chiark.greenend.org.uk</code>.

<h2>Mailinglists</h2>

I have set up mailinglists <code>adns-announce</code> and
<code>adns-discuss</code>.  The announcements list is moderated and
will contain only announcements of important bugs, new versions, &c.
The bug reports address mentioned above is also a mailing list; feel
free to subscribe to it.

<p>

There are
<A href="http://www.chiark.greenend.org.uk/mailman/listinfo">archives
and subscription web pages</A>, or you can subscribe by sending mail
containing the word `subscribe' to
<code>adns-announce-REQUEST@chiark.greenend.org.uk</code> or
<code>adns-discuss-REQUEST@chiark.greenend.org.uk</code>.

<h2>Download</h2>

Available for download from
<A href="http://www.chiark.greenend.org.uk/~ian/adns/">chiark.greenend.org.uk</A>
are:
<ul>
<li>The <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz">current beta version</A>
    as a gzipped tarfile.
<li><A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">adns.h</A>
    API header file with comments (currently there is no manual, sorry).
<li>All versions released so far are also available via
    <A href="ftp://ftp.chiark.greenend.org.uk/users/ian/adns/">anonymous
    FTP</A>.
<li>A mirror of my CVS repository is available via rsync from
    <code>rsync.chiark.greenend.org.uk::ftp/users/ian/cvs-pub/adns</code>
    (use FTP first to find your way around), or via
    <A href="http://www.chiark.greenend.org.uk/ucgi/~ijackson/cvsweb/adns/">cvsweb</A>.
</ul>

adns is also available from the
<A href="http://www.gnu.org/">GNU Project</A> FTP servers and their
<A href="http://www.gnu.org/order/ftp.html">mirrors</A>.

<h2>Copyright and licensing</h2>

<kbd>adns</kbd> is Copyright 1997-2000 Ian Jackson, Copyright 1999
Tony Finch, and Copyright (C) 1991 Massachusetts Institute of
Technology.

<p>

<kbd>adns</kbd> is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

<p>

This program and documentation is distributed in the hope that it will
be useful, but <em>without any warranty</em>; without even the implied
warranty of <em>merchantability</em> or <em>fitness for a particular
purpose</em>.  See the
<A href="http://www.chiark.greenend.org.uk/~ian/COPYING.txt">GNU
General Public License</A> for more details.

<p>

You should have received a copy of the GNU General Public License
along with <kbd>adns</kbd>, or one should be available above; if not,
write to the
<A href="http://www.fsf.org/">Free Software Foundation</A>,
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA,
or email <code>adns-maint@chiark.greenend.org.uk</code>.

<p>

<hr>
<A href="http://www.chiark.greenend.org.uk/">Ian Jackson</A> / 
<A href="mailto:adns-maint@chiark.greenend.org.uk"><tt>adns-maint@chiark.greenend.org.uk</tt></A>;
more <A href="http://www.chiark.greenend.org.uk/~ian/software/">free
software</A> by me.
<p>

<A href="http://www.gnu.org/">GNU home page</A>;
<A href="http://www.chiark.greenend.org.uk/">chiark home page</A>;
<A href="/">site or mirror home page</A>
<p>

This web page is Copyright (C)1996-2000 Ian Jackson.  See the
<A href="http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html">Copyright/acknowledgements</A>.
<p>

Use any browser -
<A href="http://www.anybrowser.org/campaign/">Campaign for a non-browser-specific WWW</A>

</body>
</html>
Commit	Line	Data
630bf698	1	<html><head><title>adns - advanced, alternative, asynchronous resolver</title>
630bf698	2	<!--
8e5a4960	3	Note: this file is maintained in Ian Jackson's private CVS.
630bf698	4
8e5a4960	5	It is served on the GNU site and also from my own system, under the
	6	URL http://www.chiark.greenend.org.uk/adns/ Please ensure that all
	7	links continine to be correct both for www.gnu.org and chiark.
630bf698	8
	9	$Id$
	10	-->
	11	<link rev="made" href="mailto:adns-maint@chiark.greenend.org.uk">
	12	</head>
	13	<body>
	14	<h1>GNU adns</h1>
	15
	16	<strong>Advanced, easy to use, asynchronous-capable DNS client
	17	library and utilities.</strong>
	18
	19	<p>
	20
8e5a4960	21	adns is a resolver library for C (and C++) programs, and a collection
	22	of useful DNS resolver utilities. In contrast with the existing
	23	interfaces, gethostbyname et al and libresolv, it has the following
	24	features:
630bf698	25
	26	<ul>
	27
	28	<li>It is reasonably easy to use for simple programs which just want
	29	to translate names to addresses, look up MX records, etc.
	30
	31	<li>It can be used in an asynchronous, non-blocking, manner. Many
	32	queries can be handled simultaneously.
	33
	34	<li>Responses are decoded automatically into a natural representation
	35	for a C program - there is no need to deal with DNS packet formats.
	36
	37	<li>Sanity checking (eg, name syntax checking, reverse/forward
	38	correspondence, CNAME pointing to CNAME) is performed automatically.
	39
	40	<li>Time-to-live, CNAME and other similar information is returned in
	41	an easy-to-use form, without getting in the way.
	42
	43	<li>There is no global state in the library; resolver state is an
	44	opaque data structure which the client creates explicitly. A program
	45	can have several instances of the resolver.
	46
	47	<li>Errors are reported to the application in a way that distinguishes
	48	the various causes of failure properly.
	49
	50	<li>Understands conventional resolv.conf, but this can overridden by
	51	environment variables.
	52
	53	<li>Flexibility. For example, the application can tell adns to:
8e5a4960	54	ignore environment variables (for setuid programs), disable hostname
	55	syntax sanity checks to return arbitrary data, override or ignore
	56	resolv.conf in favour of supplied configuration, etc.
630bf698	57
	58	<li>Believed to be correct ! For example, will correctly back off to
	59	TCP in case of long replies or queries, or to other nameservers if
	60	several are available. It has sensible handling of bad responses etc.
	61
	62	</ul>
	63
8e5a4960	64	<h2>DNS utility programs</h2>
8e5a4960	65
630bf698	66	adns also comes with a number of utility programs for use from the
	67	command line and in scripts:
	68
	69	<ul>
	70
	71	<li><code>adnslogres</code> is a much faster version of Apache's
	72	logresolv program.
	73
	74	<li><code>adnsresfilter</code> is a filter which copies its input to
	75	its output, replacing IP addresses by the corresponding names, without
	76	unduly delaying the output. For example, you can usefully pipe the
	77	output of netstat -n, tcpdump -ln, and the like, into it.
	78
	79	<li><code>adnshost</code> is a general-purpose DNS lookup utility
8e5a4960	80	which can be used easily in from the command line and from shell
	81	scripts to do simple lookups. In a more advanced mode it can be used
	82	as a general-purpose DNS helper program for scripting languages which
	83	can invoke and communicate with subprocesses. See the
	84	<A href="http://www.chiark.greenend.org.uk/~ian/adns/usage/adnsresfilter_usage.text">usage
	85	message</A> for a summary of its capabilities.
630bf698	86
	87	</ul>
	88
8e5a4960	89	<h2>Technical note</h2>
630bf698	90
8e5a4960	91	adns requires a real nameserver like
630bf698	92	<A href="http://www.isc.org/view.cgi?/products/BIND/index.phtml">BIND</A>
	93	or
	94	<A href="http://www.dents.org/">Dents</A> running on
	95	the same system or a nearby one, which must be willing to provide
	96	`recursive service'. I.e., adns is a `stub resolver'. All properly
	97	configured UN*X and GNU systems will already have such nameserver(s);
8e5a4960	98	they are usually listed in /etc/resolv.conf.
630bf698	99
	100	<h2>Documentation</h2>
	101
	102	I'm afraid there is no manual yet. However, competent C programmers
	103	should be able to use the library based on the
	104	<A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">commented
8e5a4960	105	adns.h header file</A>, and the usage messages for the programs should
8e5a4960	106	be sufficient.
630bf698	107
	108	<h2>Feedback</h2>
	109
	110	I'd be pleased if you would let me know if you're using my library in
	111	your project, and what you think of it.
	112
	113	<p>
	114
	115	If you are subscribed to <code>adns-discuss</code> please send
	116	feedback, including bug reports, there; otherwise send mail to
	117	<code>adns-bugreports@chiark.greenend.org.uk</code>. If you'd prefer
	118	that your message wasn't forwarded to the <code>adns-bugreports</code>
	119	list, send it to <code>adns-maint@chiark.greenend.org.uk</code>.
	120
	121	<h2>Mailinglists</h2>
	122
	123	I have set up mailinglists <code>adns-announce</code> and
	124	<code>adns-discuss</code>. The announcements list is moderated and
	125	will contain only announcements of important bugs, new versions, &c.
	126	The bug reports address mentioned above is also a mailing list; feel
	127	free to subscribe to it.
	128
	129	<p>
	130
	131	There are
	132	<A href="http://www.chiark.greenend.org.uk/mailman/listinfo">archives
	133	and subscription web pages</A>, or you can subscribe by sending mail
	134	containing the word `subscribe' to
	135	<code>adns-announce-REQUEST@chiark.greenend.org.uk</code> or
	136	<code>adns-discuss-REQUEST@chiark.greenend.org.uk</code>.
	137
	138	<h2>Download</h2>
	139
	140	Available for download from
	141	<A href="http://www.chiark.greenend.org.uk/~ian/adns/">chiark.greenend.org.uk</A>
	142	are:
	143	<ul>
	144	<li>The <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz">current beta version</A>
	145	as a gzipped tarfile.
	146	<li><A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">adns.h</A>
	147	API header file with comments (currently there is no manual, sorry).
	148	<li>All versions released so far are also available via
	149	<A href="ftp://ftp.chiark.greenend.org.uk/users/ian/adns/">anonymous
	150	FTP</A>.
	151	<li>A mirror of my CVS repository is available via rsync from
	152	<code>rsync.chiark.greenend.org.uk::ftp/users/ian/cvs-pub/adns</code>
	153	(use FTP first to find your way around), or via
	154	<A href="http://www.chiark.greenend.org.uk/ucgi/~ijackson/cvsweb/adns/">cvsweb</A>.
	155	</ul>
	156
	157	adns is also available from the
	158	<A href="http://www.gnu.org/">GNU Project</A> FTP servers and their
	159	<A href="http://www.gnu.org/order/ftp.html">mirrors</A>.
	160
	161	<h2>Copyright and licensing</h2>
	162
	163	<kbd>adns</kbd> is Copyright 1997-2000 Ian Jackson, Copyright 1999
	164	Tony Finch, and Copyright (C) 1991 Massachusetts Institute of
	165	Technology.
	166
	167	<p>
	168
	169	<kbd>adns</kbd> is free software; you can redistribute it and/or modify
	170	it under the terms of the GNU General Public License as published by
171	the Free Software Foundation; either version 2 of the License, or (at
172	your option) any later version.
173
174	<p>
175
176	This program and documentation is distributed in the hope that it will
177	be useful, but <em>without any warranty</em>; without even the implied
178	warranty of <em>merchantability</em> or <em>fitness for a particular
179	purpose</em>. See the
180	<A href="http://www.chiark.greenend.org.uk/~ian/COPYING.txt">GNU
181	General Public License</A> for more details.
182
183	<p>
184
185	You should have received a copy of the GNU General Public License
186	along with <kbd>adns</kbd>, or one should be available above; if not,
187	write to the
188	<A href="http://www.fsf.org/">Free Software Foundation</A>,
189	59 Temple Place - Suite 330, Boston, MA 02111-1307, USA,
190	or email <code>adns-maint@chiark.greenend.org.uk</code>.
191
192	<p>
193
194	<hr>
195	<A href="http://www.chiark.greenend.org.uk/">Ian Jackson</A> /
196	<A href="mailto:adns-maint@chiark.greenend.org.uk"><tt>adns-maint@chiark.greenend.org.uk</tt></A>;
197	more <A href="http://www.chiark.greenend.org.uk/~ian/software/">free
198	software</A> by me.
199	<p>
200
201	<A href="http://www.gnu.org/">GNU home page</A>;
202	<A href="http://www.chiark.greenend.org.uk/">chiark home page</A>;
203	<A href="/">site or mirror home page</A>
204	<p>
205
206	This web page is Copyright (C)1996-2000 Ian Jackson. See the
207	<A href="http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html">Copyright/acknowledgements</A>.
208	<p>
209
210	Use any browser -
211	<A href="http://www.anybrowser.org/campaign/">Campaign for a non-browser-specific WWW</A>
212
213	</body>
214	</html>