README.html

   1 <html><head><title>adns - advanced, alternative, asynchronous resolver</title>
   2 <link rev="made" href="mailto:adns-maint@chiark.greenend.org.uk">
   3 <meta name="keywords" content="adns">
   4 </head>
   5 <body>
   6 <h1>GNU adns</h1>
   7
   8 <strong>Advanced, easy to use, asynchronous-capable DNS client
   9 library and utilities.</strong>
  10
  11 <!--      Note: this file must contain portable HTML !            -->
  12 <!--                                                              -->
  13 <!--  It is served on the GNU site and also from my own system,   -->
  14 <!--  under the URL http://www.chiark.greenend.org.uk/adns/       -->
  15 <!--  Please ensure that all links continine to be correct        -->
  16 <!--  both for www.gnu.org and chiark.                            -->
  17 <!--                                                              -->
  18
  19 <p>
  20
  21 adns is a resolver library for C (and C++) programs, and a collection
  22 of useful DNS resolver utilities.
  23
  24
  25 <h2>C library</h2>
  26
  27 In contrast with the standard interfaces, gethostbyname et al and
  28 libresolv, it has the following features:
  29
  30 <ul>
  31
  32 <li>It is reasonably easy to use for simple programs which just want
  33 to translate names to addresses, look up MX records, etc.
  34
  35 <li>It can be used in an asynchronous, non-blocking, manner.  Many
  36 queries can be handled simultaneously.
  37
  38 <li>Responses are decoded automatically into a natural representation
  39 for a C program - there is no need to deal with DNS packet and RRDATA
  40 formats.
  41
  42 <li>Sanity checking (eg, name syntax checking, reverse/forward
  43 correspondence, CNAME pointing to CNAME) is performed automatically
  44 by default.
  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>adns understands conventional resolv.conf, but this can overridden
  57 by 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/docs/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/docs/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 Bug reports should be reported to the
 111 <a href="http://debbugs.gnu.org/">GNU Debbugs</a>.  Send an email
 112 to <code>submit@debbugs.gnu.org</code> and at the top of your email,
 113 in a paragraph of its own, write the single line
 114 <pre>
 115 Package: adns
 116 </pre>
 117 Your bug report will be published via to the adns-discuss list.
 118
 119 <p>
 120
 121 Feedback and discussion takes place on the <code>adns-discuss</code>
 122 list.  You can mail me privately
 123 at <code>ijackson@chiark.greenend.org.uk</code>.
 124
 125 <h2>Mailinglists</h2>
 126
 127 I have set up mailinglists <code>adns-announce</code> and
 128 <code>adns-discuss</code>.  The announcements list is moderated and
 129 will contain only announcements of important bugs, new versions, etc.
 130
 131 <p>
 132
 133 There are
 134 <A href="http://www.chiark.greenend.org.uk/mailman/listinfo">archives
 135 and subscription web pages</A>, or you can subscribe by sending mail
 136 containing the word `subscribe' to
 137 <code>adns-announce-REQUEST@chiark.greenend.org.uk</code> or
 138 <code>adns-discuss-REQUEST@chiark.greenend.org.uk</code>.
 139
 140 <h2>Documentation</h2>
 141
 142 <ul>
 143 <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adns.h.txt">adns.h
 144     API header file with documentation comments</A>
 145 <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/adnshost.txt">usage
 146     message for adnshost</A>
 147 </ul>
 148
 149 <h2>Download and source code</h2>
 150
 151 <ul>
 152 <li>The <A href="http://www.chiark.greenend.org.uk/~ian/adns/adns.tar.gz">current
 153     release</A> as a gzipped tarfile.
 154 <li><A href="http://www.chiark.greenend.org.uk/~ian/adns/ftp/">Previous
 155     versions</A> and other files (including OpenPGP signatures).
 156 <li><A href="http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git/adns.git/">master
 157     git (version control) repository browser</a>.
 158 </ul>
 159
 160 adns is also available from the
 161 <A href="http://www.gnu.org/">GNU Project</A> FTP servers and their
 162 <A href="http://www.gnu.org/order/ftp.html">mirrors</A>.
 163
 164 <h2>Installation note</h2>
 165
 166 adns requires a real nameserver like BIND running on the same system
 167 or a nearby one, which must be willing to provide `recursive service'.
 168 I.e., adns is a `stub resolver'.
 169
 170 <p>
 171 adns requires that your real nameserver is on the same machine, or
 172 connected via a secure network, so that an attacker cannot fake the
 173 replies to adns's queries.
 174
 175 <h2>References and related projects</h2>
 176
 177 <ul>
 178 <li><a href="http://code.google.com/p/adns-python">Python bindings</a>
 179    by Andy Dustman.
 180 <!-- <li><a href="http://cryp.to/hsdns/">Haskell bindings</a>
 181    by Peter Simons. -->
 182 <li><a href="http://www.lysator.liu.se/liboop/">liboop event loop library</a>
 183    has a built-in binding for adns.
 184 <li><a href="http://adns.jgaa.com/">port to MS Visual Studio 6 C++</a>
 185    by Jarle Aase.
 186 </ul>
 187
 188 <h2>Copyright and licensing</h2>
 189
 190 <kbd>adns</kbd> is Copyright 1997-2000,2003,2006,2014-2016 Ian Jackson,
 191 Copyright 2014 Mark Wooding, Copyright 1999-2000,2003,2006 Tony Finch,
 192 and Copyright (C) 1991 Massachusetts Institute of Technology.
 193
 194 <p>
 195
 196 <kbd>adns</kbd> is free software; you can redistribute it and/or modify
 197 it under the terms of the GNU General Public License as published by
 198 the Free Software Foundation; either version 3 of the License, or (at
 199 your option) any later version.
 200
 201 <p>
 202
 203 This program and documentation is distributed in the hope that it will
 204 be useful, but <em>without any warranty</em>; without even the implied
 205 warranty of <em>merchantability</em> or <em>fitness for a particular
 206 purpose</em>.  See the
 207 <A href="http://www.chiark.greenend.org.uk/~ian/adns/docs/COPYING.txt">GNU
 208 General Public License</A> for more details.
 209
 210 <p>
 211
 212 You should have received a copy of the GNU General Public License
 213 along with <kbd>adns</kbd>, or one should be available above; if not,
 214 write to the <A href="http://www.fsf.org/">Free Software Foundation</A>
 215 or email <code>ijackson@chiark.greenend.org.uk</code>.
 216
 217 <p>
 218
 219 <hr>
 220 Ian Jackson / <tt>ijackson@chiark.greenend.org.uk</tt>.
 221 <p>
 222
 223 <A href="http://www.gnu.org/">GNU home page</A>;
 224 <A href="http://www.chiark.greenend.org.uk/">chiark home page</A>;
 225 <A href="/">site or mirror home page</A>
 226 <p>
 227
 228 This web page is Copyright (C)1996-2005,2014-2016 Ian Jackson.  See the
 229 <A href="http://www.chiark.greenend.org.uk/~ian/sw-www-copy.html">Copyright/acknowledgements</A>.
 230
 231 </body>
 232 </html>