chiark / gitweb /
+ * Don't use <sys/select.h> any more, it was a mistake made in pre-1.0
[adns.git] / README.html
1 <html>
2 <head>
3 <title>adns - advanced, alternative, asynchronous resolver</title>
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
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
21 <p>
22
23 adns is a resolver library for C (and C++) programs, and a collection
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:
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:
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.
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
70 <h2>DNS utility programs</h2>
71
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
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
90 <A href="http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt">adnshost
91 usage message</A> for a summary of its capabilities.
92
93 </ul>
94
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
100 adns.h header file</A>, and the usage messages for the programs should
101 be sufficient.
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
120 will contain only announcements of important bugs, new versions, etc.
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>
139 <li>The <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz">current
140     release</A> as a gzipped tarfile.
141 <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">adns.h</A>
142     API header file with comments, and
143     <A href="http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt">usage
144     message for adnshost</A> (currently there is no manual, sorry).
145 <li>All versions released so far are also available via
146     <A href="ftp://ftp.chiark.greenend.org.uk/users/ian/adns/">anonymous
147     FTP</A> and <A href="http://www.chiark.greenend.org.uk/~ian/adns/ftp/">HTTP</A>,
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
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
169 <h2>Copyright and licensing</h2>
170
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.
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>