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