README

   1
   2                                      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 BIND or [1]Dents
  48    running on the same system or a nearby one, which must be willing to
  49    provide `recursive service'. I.e., adns is a `stub resolver'. All
  50    properly configured UN*X and GNU systems will already have such
  51    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 [2]adns.h
  57    header file (from version 0.3).
  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 [3]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 [4]chiark.greenend.org.uk are:
  85      * The [5]current pre-release version as a gzipped tarfile.
  86      * [6]adns.h API header file with comments (currently there is no
  87        manual, sorry).
  88      * All versions released so far are also available via [7]anonymous
  89        FTP.
  90
  91    adns is also available from the [8]GNU Project FTP servers and their
  92    [9]mirrors.
  93
  94 Copyright and licensing
  95
  96    adns is Copyright 1997-1999 Ian Jackson.
  97
  98    adns is free software; you can redistribute it and/or modify it under
  99    the terms of the GNU General Public License as published by the Free
 100    Software Foundation; either version 2 of the License, or (at your
 101    option) any later version.
 102
 103    This program and documentation is distributed in the hope that it will
 104    be useful, but without any warranty; without even the implied warranty
 105    of merchantability or fitness for a particular purpose. See the
 106    [10]GNU General Public License for more details.
 107
 108    You should have received a copy of the GNU General Public License
 109    along with adns, or one should be available above; if not, write to
 110    the [11]Free Software Foundation, 59 Temple Place - Suite 330, Boston,
 111    MA 02111-1307, USA, or email adns-maint@chiark.greenend.org.uk.
 112      _________________________________________________________________
 113
 114    [12]Ian Jackson / [13]adns-maint@chiark.greenend.org.uk; more [14]free
 115    software by me.
 116
 117    [15]GNU home page; [16]chiark home page; [17]site or mirror home page
 118
 119    This web page is Copyright (C)1996-1999 Ian Jackson. See the
 120    [18]Copyright/acknowledgements.
 121
 122    Use any browser - [19]Campaign for a non-browser-specific WWW
 123
 124 References
 125
 126    1. http://www.dents.org/
 127    2. http://www.chiark.greenend.org.uk/~ian/adns/adns.h.0.3.txt
 128    3. http://www.chiark.greenend.org.uk/mailman/listinfo
 129    4. http://www.chiark.greenend.org.uk/~ian/adns/
 130    5. http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz
 131    6. http://www.chiark.greenend.org.uk/~ian/adns/adns.h.0.3.txt
 132    7. ftp://ftp.chiark.greenend.org.uk/users/ian/adns/
 133    8. http://www.gnu.org/
 134    9. http://www.gnu.org/order/ftp.html
 135   10. http://www.chiark.greenend.org.uk/~ian/COPYING.txt
 136   11. http://www.fsf.org/
 137   12. http://www.chiark.greenend.org.uk/
 138   13. mailto:adns-maint@chiark.greenend.org.uk
 139   14. http://www.chiark.greenend.org.uk/~ian/software/
 140   15. http://www.gnu.org/
 141   16. http://www.chiark.greenend.org.uk/
 142   17. http://www.chiark.greenend.org.uk/
 143   18. http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html
 144   19. http://www.anybrowser.org/campaign/