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