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