README.html

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