README.html

   1 <html><head><title>adns - advanced, alternative, asynchronous resolver</title>
   2 <!--
   3   Note: this file is maintained in Ian Jackson's private CVS.
   4
   5   It is served on the GNU site and also from my own system, under the
   6   URL http://www.chiark.greenend.org.uk/adns/ Please ensure that all
   7   links continine to be correct both for www.gnu.org and chiark.
   8
   9   $Id$
  10   -->
  11 <link rev="made" href="mailto:adns-maint@chiark.greenend.org.uk">
  12 </head>
  13 <body>
  14 <h1>GNU adns</h1>
  15
  16 <strong>Advanced, easy to use, asynchronous-capable DNS client
  17 library and utilities.</strong>
  18
  19 <p>
  20
  21 adns is a resolver library for C (and C++) programs, and a collection
  22 of useful DNS resolver utilities.  In contrast with the existing
  23 interfaces, gethostbyname et al and libresolv, it has the following
  24 features:
  25
  26 <ul>
  27
  28 <li>It is reasonably easy to use for simple programs which just want
  29 to translate names to addresses, look up MX records, etc.
  30
  31 <li>It can be used in an asynchronous, non-blocking, manner.  Many
  32 queries can be handled simultaneously.
  33
  34 <li>Responses are decoded automatically into a natural representation
  35 for a C program - there is no need to deal with DNS packet formats.
  36
  37 <li>Sanity checking (eg, name syntax checking, reverse/forward
  38 correspondence, CNAME pointing to CNAME) is performed automatically.
  39
  40 <li>Time-to-live, CNAME and other similar information is returned in
  41 an easy-to-use form, without getting in the way.
  42
  43 <li>There is no global state in the library; resolver state is an
  44 opaque data structure which the client creates explicitly.  A program
  45 can have several instances of the resolver.
  46
  47 <li>Errors are reported to the application in a way that distinguishes
  48 the various causes of failure properly.
  49
  50 <li>Understands conventional resolv.conf, but this can overridden by
  51 environment variables.
  52
  53 <li>Flexibility.  For example, the application can tell adns to:
  54 ignore environment variables (for setuid programs), disable hostname
  55 syntax sanity checks to return arbitrary data, override or ignore
  56 resolv.conf in favour of supplied configuration, etc.
  57
  58 <li>Believed to be correct !  For example, will correctly back off to
  59 TCP in case of long replies or queries, or to other nameservers if
  60 several are available.  It has sensible handling of bad responses etc.
  61
  62 </ul>
  63
  64 <h2>DNS utility programs</h2>
  65
  66 adns also comes with a number of utility programs for use from the
  67 command line and in scripts:
  68
  69 <ul>
  70
  71 <li><code>adnslogres</code> is a much faster version of Apache's
  72 logresolv program.
  73
  74 <li><code>adnsresfilter</code> is a filter which copies its input to
  75 its output, replacing IP addresses by the corresponding names, without
  76 unduly delaying the output.  For example, you can usefully pipe the
  77 output of netstat -n, tcpdump -ln, and the like, into it.
  78
  79 <li><code>adnshost</code> is a general-purpose DNS lookup utility
  80 which can be used easily in from the command line and from shell
  81 scripts to do simple lookups.  In a more advanced mode it can be used
  82 as a general-purpose DNS helper program for scripting languages which
  83 can invoke and communicate with subprocesses.  See the
  84 <A href="http://www.chiark.greenend.org.uk/~ian/adns/usage/adnsresfilter_usage.text">usage
  85 message</A> for a summary of its capabilities.
  86
  87 </ul>
  88
  89 <h2>Technical note</h2>
  90
  91 adns requires a real nameserver like
  92 <A href="http://www.isc.org/view.cgi?/products/BIND/index.phtml">BIND</A>
  93 or
  94 <A href="http://www.dents.org/">Dents</A> running on
  95 the same system or a nearby one, which must be willing to provide
  96 `recursive service'.  I.e., adns is a `stub resolver'.  All properly
  97 configured UN*X and GNU systems will already have such nameserver(s);
  98 they are usually listed in /etc/resolv.conf.
  99
 100 <h2>Documentation</h2>
 101
 102 I'm afraid there is no manual yet.  However, competent C programmers
 103 should be able to use the library based on the
 104 <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">commented
 105 adns.h header file</A>, and the usage messages for the programs should
 106 be sufficient.
 107
 108 <h2>Feedback</h2>
 109
 110 I'd be pleased if you would let me know if you're using my library in
 111 your project, and what you think of it.
 112
 113 <p>
 114
 115 If you are subscribed to <code>adns-discuss</code> please send
 116 feedback, including bug reports, there; otherwise send mail to
 117 <code>adns-bugreports@chiark.greenend.org.uk</code>.  If you'd prefer
 118 that your message wasn't forwarded to the <code>adns-bugreports</code>
 119 list, send it to <code>adns-maint@chiark.greenend.org.uk</code>.
 120
 121 <h2>Mailinglists</h2>
 122
 123 I have set up mailinglists <code>adns-announce</code> and
 124 <code>adns-discuss</code>.  The announcements list is moderated and
 125 will contain only announcements of important bugs, new versions, &c.
 126 The bug reports address mentioned above is also a mailing list; feel
 127 free to subscribe to it.
 128
 129 <p>
 130
 131 There are
 132 <A href="http://www.chiark.greenend.org.uk/mailman/listinfo">archives
 133 and subscription web pages</A>, or you can subscribe by sending mail
 134 containing the word `subscribe' to
 135 <code>adns-announce-REQUEST@chiark.greenend.org.uk</code> or
 136 <code>adns-discuss-REQUEST@chiark.greenend.org.uk</code>.
 137
 138 <h2>Download</h2>
 139
 140 Available for download from
 141 <A href="http://www.chiark.greenend.org.uk/~ian/adns/">chiark.greenend.org.uk</A>
 142 are:
 143 <ul>
 144 <li>The <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz">current beta version</A>
 145     as a gzipped tarfile.
 146 <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.h.txt">adns.h</A>
 147     API header file with comments (currently there is no manual, sorry).
 148 <li>All versions released so far are also available via
 149     <A href="ftp://ftp.chiark.greenend.org.uk/users/ian/adns/">anonymous
 150     FTP</A>.
 151 <li>A mirror of my CVS repository is available via rsync from
 152     <code>rsync.chiark.greenend.org.uk::ftp/users/ian/cvs-pub/adns</code>
 153     (use FTP first to find your way around), or via
 154     <A href="http://www.chiark.greenend.org.uk/ucgi/~ijackson/cvsweb/adns/">cvsweb</A>.
 155 </ul>
 156
 157 adns is also available from the
 158 <A href="http://www.gnu.org/">GNU Project</A> FTP servers and their
 159 <A href="http://www.gnu.org/order/ftp.html">mirrors</A>.
 160
 161 <h2>Copyright and licensing</h2>
 162
 163 <kbd>adns</kbd> is Copyright 1997-2000 Ian Jackson, Copyright 1999
 164 Tony Finch, and Copyright (C) 1991 Massachusetts Institute of
 165 Technology.
 166
 167 <p>
 168
 169 <kbd>adns</kbd> is free software; you can redistribute it and/or modify
 170 it under the terms of the GNU General Public License as published by
 171 the Free Software Foundation; either version 2 of the License, or (at
 172 your option) any later version.
 173
 174 <p>
 175
 176 This program and documentation is distributed in the hope that it will
 177 be useful, but <em>without any warranty</em>; without even the implied
 178 warranty of <em>merchantability</em> or <em>fitness for a particular
 179 purpose</em>.  See the
 180 <A href="http://www.chiark.greenend.org.uk/~ian/COPYING.txt">GNU
 181 General Public License</A> for more details.
 182
 183 <p>
 184
 185 You should have received a copy of the GNU General Public License
 186 along with <kbd>adns</kbd>, or one should be available above; if not,
 187 write to the
 188 <A href="http://www.fsf.org/">Free Software Foundation</A>,
 189 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA,
 190 or email <code>adns-maint@chiark.greenend.org.uk</code>.
 191
 192 <p>
 193
 194 <hr>
 195 <A href="http://www.chiark.greenend.org.uk/">Ian Jackson</A> /
 196 <A href="mailto:adns-maint@chiark.greenend.org.uk"><tt>adns-maint@chiark.greenend.org.uk</tt></A>;
 197 more <A href="http://www.chiark.greenend.org.uk/~ian/software/">free
 198 software</A> by me.
 199 <p>
 200
 201 <A href="http://www.gnu.org/">GNU home page</A>;
 202 <A href="http://www.chiark.greenend.org.uk/">chiark home page</A>;
 203 <A href="/">site or mirror home page</A>
 204 <p>
 205
 206 This web page is Copyright (C)1996-2000 Ian Jackson.  See the
 207 <A href="http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html">Copyright/acknowledgements</A>.
 208 <p>
 209
 210 Use any browser -
 211 <A href="http://www.anybrowser.org/campaign/">Campaign for a non-browser-specific WWW</A>
 212
 213 </body>
 214 </html>