README

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