[adns] / README.html

<html>
<head>
<title>adns - advanced, alternative, asynchronous resolver</title>
<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>

<!-- 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$        -->   

<p>

adns is a resolver library for C (and C++) programs, and a collection
of useful DNS resolver utilities.


<h2>C library</h2>

In contrast with the standard 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/adnshost.txt">adnshost
usage message</A> for a summary of its capabilities.

</ul>

<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, etc.
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
    release</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, and
    <A href="http://www.chiark.greenend.org.uk/~ian/adns/adnsresfilter.txt">usage
    message for adnshost</A> (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> and <A href="http://www.chiark.greenend.org.uk/~ian/adns/ftp/">HTTP</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>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>Copyright and licensing</h2>

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