chiark / gitweb /
Correct type of various printf arguments: ptrdiff_t != int
[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 Forthcoming:
59
60    I hope that future versions may also have the following features:
61      * The library should be useable by threads in a multithreaded
62        program in a natural way. It should multiplex many threads'
63        queries through a single query socket.
64      * IPv6 support.
65      * Some kind of awareness of DNSSEC.
66      * Possibly some very limited caching behaviour.
67      * There was, at one point, a draft native Perl interface from Tony
68        Finch.
69
70 Documentation
71
72    I'm afraid there is no manual yet. However, competent C programmers
73    should be able to use the library based on the [2]commented adns.h
74    header file, and the usage messages for the programs should be
75    sufficient.
76
77 Feedback
78
79    I'd be pleased if you would let me know if you're using my library in
80    your project, and what you think of it.
81
82    If you are subscribed to adns-discuss please send feedback, including
83    bug reports, there; otherwise send mail to
84    adns-bugreports@chiark.greenend.org.uk. If you'd prefer that your
85    message wasn't forwarded to the adns-bugreports list, send it to
86    adns-maint@chiark.greenend.org.uk.
87
88 Mailinglists
89
90    I have set up mailinglists adns-announce and adns-discuss. The
91    announcements list is moderated and will contain only announcements of
92    important bugs, new versions, etc. The bug reports address mentioned
93    above is also a mailing list; feel free to subscribe to it.
94
95    There are [3]archives and subscription web pages, or you can subscribe
96    by sending mail containing the word `subscribe' to
97    adns-announce-REQUEST@chiark.greenend.org.uk or
98    adns-discuss-REQUEST@chiark.greenend.org.uk.
99
100 Download
101
102    Available for download from [4]chiark.greenend.org.uk are:
103      * The [5]current release as a gzipped tarfile.
104      * [6]adns.h API header file with comments, and [7]usage message for
105        adnshost (currently there is no manual, sorry).
106      * All versions released so far are also available via [8]anonymous
107        FTP and [9]HTTP.
108
109    You can also access the project CVS repositories:
110      * A mirror of the source code repository is available via rsync from
111        rsync.chiark.greenend.org.uk::ftp/users/ian/cvs-pub/adns (use FTP
112        first to find your way around), or via [10]cvsweb.
113      * This web page is maintained in [11]Savannah, where you can browse
114        the [12]webpage CVS.
115
116    adns is also available from the [13]GNU Project FTP servers and their
117    [14]mirrors.
118
119 Technical note
120
121    adns requires a real nameserver like [15]BIND or [16]Dents running on
122    the same system or a nearby one, which must be willing to provide
123    `recursive service'. I.e., adns is a `stub resolver'. All properly
124    configured UN*X and GNU systems will already have such nameserver(s);
125    they are usually listed in /etc/resolv.conf.
126
127 References and related projects
128
129    There is a [17]port to MS Visual Studio 6 C++ by Jarle Aase.
130
131 Copyright and licensing
132
133    adns is Copyright 1997-2005 Ian Jackson, Copyright 1999-2004 Tony
134    Finch, and Copyright (C) 1991 Massachusetts Institute of Technology.
135
136    adns is free software; you can redistribute it and/or modify it under
137    the terms of the GNU General Public License as published by the Free
138    Software Foundation; either version 2 of the License, or (at your
139    option) any later version.
140
141    This program and documentation is distributed in the hope that it will
142    be useful, but without any warranty; without even the implied warranty
143    of merchantability or fitness for a particular purpose. See the
144    [18]GNU General Public License for more details.
145
146    You should have received a copy of the GNU General Public License
147    along with adns, or one should be available above; if not, write to
148    the [19]Free Software Foundation, 59 Temple Place - Suite 330, Boston,
149    MA 02111-1307, USA, or email adns-maint@chiark.greenend.org.uk.
150      _________________________________________________________________
151
152    [20]Ian Jackson / [21]adns-maint@chiark.greenend.org.uk; more [22]free
153    software by me.
154
155    [23]GNU home page; [24]chiark home page; [25]site or mirror home page
156
157    This web page is Copyright (C)1996-2005 Ian Jackson. See the
158    [26]Copyright/acknowledgements.
159
160    Use any browser - [27]Campaign for a non-browser-specific WWW
161
162 References
163
164    1. http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt
165    2. http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt
166    3. http://www.chiark.greenend.org.uk/mailman/listinfo
167    4. http://www.chiark.greenend.org.uk/~ian/adns/
168    5. http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz
169    6. http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt
170    7. http://www.chiark.greenend.org.uk/~ian/adns/adnshost.txt
171    8. ftp://ftp.chiark.greenend.org.uk/users/ian/adns/
172    9. http://www.chiark.greenend.org.uk/~ian/adns/ftp/
173   10. http://www.chiark.greenend.org.uk/ucgi/~ijackson/cvsweb/adns/
174   11. http://savannah.gnu.org/
175   12. http://savannah.gnu.org/cgi-bin/viewcvs/software/adns/?cvsroot=www.gnu.org
176   13. http://www.gnu.org/
177   14. http://www.gnu.org/order/ftp.html
178   15. http://www.isc.org/view.cgi?/products/BIND/index.phtml
179   16. http://www.dents.org/
180   17. http://adns.jgaa.com/
181   18. http://www.chiark.greenend.org.uk/~ian/COPYING.txt
182   19. http://www.fsf.org/
183   20. http://www.chiark.greenend.org.uk/
184   21. mailto:adns-maint@chiark.greenend.org.uk
185   22. http://www.chiark.greenend.org.uk/~ian/software/
186   23. http://www.gnu.org/
187   24. http://www.chiark.greenend.org.uk/
188   25. file://localhost/
189   26. http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html
190   27. http://www.anybrowser.org/campaign/