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 will be useable by threads in a multithreaded program
  41        in a natural way. It will multiplex many threads' queries through
  42        a single query socket.
  43      * Limited caching behaviour.
  44      * IPv6 support.
  45
  46    (Technical note: adns requires a real nameserver like BIND or [1]Dents
  47    running on the same system or a nearby one, which must be willing to
  48    provide `recursive service'. I.e., adns is a `stub resolver'. All
  49    properly configured UN*X and GNU systems will already have such
  50    nameserver(s); they are usually listed in /etc/resolv.conf.)
  51
  52 Documentation
  53
  54    I'm afraid there is no manual yet. However, competent C programmers
  55    should be able to use the library based on the commented [2]adns.h
  56    header file (from version 0.1).
  57
  58 Feedback
  59
  60    If you are subscribed to adns-discuss please send bug reports there;
  61    otherwise mail them to adns-bugreports@chiark.greenend.org.uk.
  62
  63 Mailinglists
  64
  65    I have set up mailinglists adns-announce and adns-discuss. The
  66    announcements list is moderated and will contain only announcements of
  67    important bugs, new versions, &c. The bug reports address mentioned
  68    above is also a mailing list; feel free to subscribe to it.
  69
  70    There are [3]archives and subscription web pages, or you can subscribe
  71    by sending mail containing the word `subscribe' to
  72    adns-announce-REQUEST@chiark.greenend.org.uk or
  73    adns-discuss-REQUEST@chiark.greenend.org.uk.
  74
  75 Download
  76
  77    Available for download from [4]chiark.greenend.org.uk are:
  78      * The [5]current pre-release version as a gzipped tarfile.
  79      * [6]adns.h API header file with comments (currently there is no
  80        manual, sorry).
  81      * All versions released so far are also available via [7]anonymous
  82        FTP.
  83
  84    adns is also available from the [8]GNU Project FTP servers and their
  85    [9]mirrors.
  86
  87 Copyright and licensing
  88
  89    adns is Copyright 1997-1999 Ian Jackson.
  90
  91    adns is free software; you can redistribute it and/or modify it under
  92    the terms of the GNU General Public License as published by the Free
  93    Software Foundation; either version 2 of the License, or (at your
  94    option) any later version.
  95
  96    This program and documentation is distributed in the hope that it will
  97    be useful, but without any warranty; without even the implied warranty
  98    of merchantability or fitness for a particular purpose. See the
  99    [10]GNU General Public License for more details.
 100
 101    You should have received a copy of the GNU General Public License
 102    along with adns, or one should be available above; if not, write to
 103    the [11]Free Software Foundation, 59 Temple Place - Suite 330, Boston,
 104    MA 02111-1307, USA, or email adns-maint@chiark.greenend.org.uk.
 105      _________________________________________________________________
 106
 107    [12]Ian Jackson / [13]adns-maint@chiark.greenend.org.uk; more [14]free
 108    software by me.
 109
 110    [15]GNU home page; [16]chiark home page; [17]site or mirror home page
 111
 112    This web page is Copyright (C)1996-1999 Ian Jackson. See the
 113    [18]Copyright/acknowledgements.
 114
 115    Use any browser - [19]Campaign for a non-browser-specific WWW
 116
 117 References
 118
 119    1. http://www.dents.org/
 120    2. http://www.chiark.greenend.org.uk/~ian/adns/adns.h.0.1.txt
 121    3. http://www.chiark.greenend.org.uk/mailman/listinfo
 122    4. http://www.chiark.greenend.org.uk/~ian/adns/
 123    5. http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz
 124    6. http://www.chiark.greenend.org.uk/~ian/adns/adns.h.0.1.txt
 125    7. ftp://ftp.chiark.greenend.org.uk/users/ian/adns/
 126    8. http://www.gnu.org/
 127    9. http://www.gnu.org/order/ftp.html
 128   10. http://www.chiark.greenend.org.uk/~ian/COPYING.txt
 129   11. http://www.fsf.org/
 130   12. http://www.chiark.greenend.org.uk/
 131   13. mailto:adns-maint@chiark.greenend.org.uk
 132   14. http://www.chiark.greenend.org.uk/~ian/software/
 133   15. http://www.gnu.org/
 134   16. http://www.chiark.greenend.org.uk/
 135   17. http://www.chiark.greenend.org.uk/
 136   18. http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html
 137   19. http://www.anybrowser.org/campaign/