From: ian Date: Sun, 17 Sep 2000 00:24:24 +0000 (+0000) Subject: Initial checkin from my copy of GNU WWW CVS. X-Git-Tag: rel-adns-pre-1-0--1~6 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=adns.git;a=commitdiff_plain;h=630bf6981f8ce925697e3668346e9d5267f2800c Initial checkin from my copy of GNU WWW CVS. --- diff --git a/README.html b/README.html new file mode 100644 index 0000000..7d44601 --- /dev/null +++ b/README.html @@ -0,0 +1,231 @@ +adns - advanced, alternative, asynchronous resolver + + + + +

GNU adns

+ +Advanced, easy to use, asynchronous-capable DNS client +library and utilities. + +

+ +adns is a resolver library for C (and C++) programs. In contrast with +the existing interfaces, gethostbyname et al and libresolv, it has the +following features: + +

It is reasonably easy to use for simple programs which just want +to translate names to addresses, look up MX records, etc. + +
It can be used in an asynchronous, non-blocking, manner. Many +queries can be handled simultaneously. + +
Responses are decoded automatically into a natural representation +for a C program - there is no need to deal with DNS packet formats. + +
Sanity checking (eg, name syntax checking, reverse/forward +correspondence, CNAME pointing to CNAME) is performed automatically. + +
Time-to-live, CNAME and other similar information is returned in +an easy-to-use form, without getting in the way. + +
There is no global state in the library; resolver state is an +opaque data structure which the client creates explicitly. A program +can have several instances of the resolver. + +
Errors are reported to the application in a way that distinguishes +the various causes of failure properly. + +
Understands conventional resolv.conf, but this can overridden by +environment variables. + +
Flexibility. For example, the application can tell adns to: +ignore environment variables (for setuid programs), disable sanity +checks eg to return arbitrary data, override or ignore resolv.conf in +favour of supplied configuration, etc. + +
Believed to be correct ! For example, will correctly back off to +TCP in case of long replies or queries, or to other nameservers if +several are available. It has sensible handling of bad responses etc. + +

+ +adns also comes with a number of utility programs for use from the +command line and in scripts: + +

adnslogres is a much faster version of Apache's +logresolv program. + +
adnsresfilter is a filter which copies its input to +its output, replacing IP addresses by the corresponding names, without +unduly delaying the output. For example, you can usefully pipe the +output of netstat -n, tcpdump -ln, and the like, into it. + +
adnshost is a general-purpose DNS lookup utility +which can be used easily in shell scripts to do simple lookups. In a +more advanced mode it can be used as a general-purpose DNS helper +program for scripting languages which can invoke and communicate with +subprocesses. + +

+ +

Forthcoming:

+ +A native Perl interface is in the works, thanks to Tony Finch. + +

+ +I hope that future versions may also have the following features: + +

The library should be useable by threads in a multithreaded +program in a natural way. It should multiplex many threads' queries +through a single query socket. + +
IPv6 support. + +
Some kind of awareness of DNSSEC. + +
Possibly some very limited caching behaviour. + +

+ +(Technical note: adns requires a real nameserver like +BIND +or +Dents running on +the same system or a nearby one, which must be willing to provide +`recursive service'. I.e., adns is a `stub resolver'. All properly +configured UN*X and GNU systems will already have such nameserver(s); +they are usually listed in /etc/resolv.conf.) + +

Documentation

+ +I'm afraid there is no manual yet. However, competent C programmers +should be able to use the library based on the +commented +adns.h header file. + +

Feedback

+ +I'd be pleased if you would let me know if you're using my library in +your project, and what you think of it. + +

+ +If you are subscribed to adns-discuss please send +feedback, including bug reports, there; otherwise send mail to +adns-bugreports@chiark.greenend.org.uk. If you'd prefer +that your message wasn't forwarded to the adns-bugreports +list, send it to adns-maint@chiark.greenend.org.uk. + +

Mailinglists

+ +I have set up mailinglists adns-announce and +adns-discuss. The announcements list is moderated and +will contain only announcements of important bugs, new versions, &c. +The bug reports address mentioned above is also a mailing list; feel +free to subscribe to it. + +

+ +There are +archives +and subscription web pages, or you can subscribe by sending mail +containing the word `subscribe' to +adns-announce-REQUEST@chiark.greenend.org.uk or +adns-discuss-REQUEST@chiark.greenend.org.uk. + +

Download

+ +Available for download from +chiark.greenend.org.uk +are: +

The current beta version + as a gzipped tarfile. +
adns.h + API header file with comments (currently there is no manual, sorry). +
All versions released so far are also available via + anonymous + FTP. +
A mirror of my CVS repository is available via rsync from + rsync.chiark.greenend.org.uk::ftp/users/ian/cvs-pub/adns + (use FTP first to find your way around), or via + cvsweb. +

+ +adns is also available from the +GNU Project FTP servers and their +mirrors. + +

Copyright and licensing

+ +adns is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or (at +your option) any later version. + +

+ +This program and documentation is distributed in the hope that it will +be useful, but without any warranty; without even the implied +warranty of merchantability or fitness for a particular +purpose. See the +GNU +General Public License for more details. + +

+ +You should have received a copy of the GNU General Public License +along with adns, or one should be available above; if not, +write to the +Free Software Foundation, +59 Temple Place - Suite 330, Boston, MA 02111-1307, USA, +or email adns-maint@chiark.greenend.org.uk. + +

+ +

+Ian Jackson / +adns-maint@chiark.greenend.org.uk; +more free +software by me. +

+ +GNU home page; +chiark home page; +site or mirror home page +

+ +Use any browser - +Campaign for a non-browser-specific WWW + + +