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