doc/README.html

   1 <?xml version="1.0" encoding="iso-8859-1"?> <!-- -*-html-helper-*- -->
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4
   5 <head>
   6 <title>libasyncns 0.8</title>
   7 <link rel="stylesheet" type="text/css" href="style.css" />
   8 </head>
   9
  10 <body>
  11 <h1><a name="top">libasyncns 0.8</a></h1>
  12
  13 <p><i>Copyright 2005-2009 Lennart Poettering &lt;mznflapaf (at) 0pointer (dot) de&gt;</i></p>
  14
  15 <ul class="toc">
  16     <li><a href="#license">License</a></li>
  17     <li><a href="#news">News</a></li>
  18     <li><a href="#overview">Overview</a></li>
  19     <li><a href="#status">Current Status</a></li>
  20     <li><a href="#documentation">Documentation</a></li>
  21     <li><a href="#requirements">Requirements</a></li>
  22     <li><a href="#installation">Installation</a></li>
  23     <li><a href="#acks">Acknowledgements</a></li>
  24     <li><a href="#download">Download</a></li>
  25 </ul>
  26
  27 <h2><a name="license">License</a></h2>
  28
  29 <p>This program is free software; you can redistribute it and/or
  30 modify it under the terms of the GNU Lesser General Public License as
  31 published by the Free Software Foundation, either version 2.1 of the
  32 License, or (at your option) any later version.</p>
  33
  34 <p>This program is distributed in the hope that it will be useful, but
  35 WITHOUT ANY WARRANTY; without even the implied warranty of
  36 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  37 Lesser General Public License for more details.</p>
  38
  39 <h2><a name="news">News</a></h2>
  40
  41 <div class="news-date">Thu 15 Oct
  42 2009: </div> <p class="news-text"><a href="http://0pointer.de/lennart/projects/libasyncns/libasyncns-0.8.tar.gz">Version
  43 0.8</a> released; changes include: various smaller fixes.</p>
  44
  45 <div class="news-date">Tue 28 Oct
  46 2008: </div> <p class="news-text"><a href="http://0pointer.de/lennart/projects/libasyncns/libasyncns-0.7.tar.gz">Version
  47 0.7</a> released; changes include: rework thread shutdown logic.</p>
  48
  49 <div class="news-date">Fri 24 Oct
  50 2008: </div> <p class="news-text"><a href="http://0pointer.de/lennart/projects/libasyncns/libasyncns-0.6.tar.gz">Version
  51 0.6</a> released; changes include: save and restore <tt>h_errno</tt>
  52 in addition to <tt>errno</tt>; drop usage of pthread's cancelling
  53 since it is problematic on some platforms.</p>
  54
  55 <div class="news-date">Sun 17 Aug
  56 2008: </div> <p class="news-text"><a href="http://0pointer.de/lennart/projects/libasyncns/libasyncns-0.5.tar.gz">Version
  57 0.5</a> released; changes include: fix getaddrinfo() serialization.</p>
  58
  59 <div class="news-date">Sun 27 Jul
  60 2008: </div> <p class="news-text"><a href="http://0pointer.de/lennart/projects/libasyncns/libasyncns-0.4.tar.gz">Version
  61 0.4</a> released; changes include: rework error handling logic,
  62 add <tt>asyncns_freeanswer()</tt>, a lot of fixes</p>
  63
  64 <div class="news-date">Wed 23 May 2007: </div> <p class="news-text"><a
  65 href="http://0pointer.de/lennart/projects/libasyncns/libasyncns-0.3.tar.gz">Version 0.3</a> released;
  66 changes include: build fixes: properly detect <tt>res_query()</tt> on
  67 Linux/AMD64, support older autoconf versions</p>
  68
  69 <div class="news-date">Fri 16 Feb 2007: </div> <p class="news-text"><a
  70 href="http://0pointer.de/lennart/projects/libasyncns/libasyncns-0.2.tar.gz">Version 0.2</a> released;
  71 changes include: <tt>res_query()</tt> support; minor bug fixes; doc updates</p>
  72
  73 <div class="news-date">Sat 8 Jan 2005: </div> <p class="news-text"><a
  74 href="http://0pointer.de/lennart/projects/libasyncns/libasyncns-0.1.tar.gz">Version 0.1</a> released</p>
  75
  76 <h2><a name="overview">Overview</a></h2>
  77
  78 <p><tt>libasyncns</tt> is a C library for Linux/Unix for executing name
  79 service queries asynchronously. It is an asynchronous wrapper around
  80 <tt>getaddrinfo(3)</tt>, <tt>getnameinfo(3)</tt>, <tt>res_query(3)</tt> and
  81 <tt>res_search(3)</tt> from <tt>libc</tt> and <tt>libresolv</tt>.</p>
  82
  83 <p>In contrast to GNU's asynchronous name resolving API
  84 <tt>getaddrinfo_a()</tt>, <tt>libasyncns</tt> does not make use of
  85 UNIX signals for reporting completion of name queries. Instead, the
  86 API exports a standard UNIX file descriptor which may be integerated
  87 cleanly into custom main loops.</p>
  88
  89 <p>In contrast to asynchronous DNS resolving libraries like <tt><a
  90 href="http://libdenise.sourceforge.net/">libdenise</a></tt>, <tt><a
  91 href="http://www.skarnet.org/software/skadns/">skadns</a></tt>, <tt><a
  92 href="http://www.chiark.greenend.org.uk/~ian/adns/">adns</a></tt>,
  93 <tt>libasyncns</tt> is just an asynchronous wrapper around the libc's
  94 synchronous <tt>getaddrinfo()</tt> API, which has the advantage of
  95 allowing name resolution using techniques like <a
  96 href="http://0pointer.de/lennart/projects/nss-mdns/">Multicast
  97 DNS</a>, LDAP or NIS using standard <tt>libc</tt> NSS (Name Service
  98 Switch) modules. <tt>libasyncns</tt> is compatible with IPv6 if the
  99 underlying <tt>libc</tt> is.</p>
 100
 101 <p><tt>libasyncns</tt> is very tiny, consisting of just one header and
 102 one source file. It has no dependencies besides <tt>libc</tt>.</p>
 103
 104 <p>By default <tt>libasyncns</tt> spawns a number of worker threads
 105 (LWPs) to process name queries. Alternatively or when POSIX Threads
 106 are not supported, <tt>libasyncns</tt> can <tt>fork()</tt> off worker
 107 processes instead.</p>
 108
 109 <h2><a name="status">Current Status</a></h2>
 110
 111 <p>Version 0.8 is quite stable and feature complete.</p>
 112
 113 <p>Damien Th&#233;bault has written a Python module <a href="https://launchpad.net/libasyncns-python">libasyncns-python</a> that wraps the libasyncns C API.</p>
 114
 115 <h2><a name="documentation">Documentation</a></h2>
 116
 117 <p>You may browse the <a href="http://www.doxygen.org/">Doxygen</a>
 118 generated <a
 119 href="http://0pointer.de/lennart/projects/libasyncns/doxygen/">programing
 120 documentation</a> the API. (Run <tt>make doxygen</tt> to generate this
 121 documentation from the source tree)</p>
 122
 123 <h2><a name="requirements">Requirements</a></h2>
 124
 125 <p>Currently, <tt>libasyncns</tt> is tested on Linux and Solaris (<tt>sparc-sun-solaris2.8</tt>) only.</p>
 126
 127 <p><tt>libasyncns</tt> was developed and tested on Debian GNU/Linux
 128 "testing" from January 2005, it should work on most other Linux
 129 distributions (and maybe Unix versions) since it uses GNU autoconf and
 130 GNU libtool for source code configuration and shared library
 131 management.</p>
 132
 133 <p><tt>libasyncns</tt> has no dependencies besides a <tt>libc</tt> that supports <tt>getaddrinfo()</tt> and <tt>res_query()</tt>.</p>
 134
 135 <h2><a name="installation">Installation</a></h2>
 136
 137 <p>As this package is made with the GNU autotools you should run
 138 <tt>./configure</tt> inside the distribution directory for configuring
 139 the source tree. After that you should run <tt>make</tt> for
 140 compilation and <tt>make install</tt> (as root) for installation of
 141 <tt>libasyncns</tt>.</p>
 142
 143 <h2><a name="acks">Acknowledgements</a></h2>
 144
 145 <p>Sjoerd Simons for the <tt>res_query()</tt> support.</p>
 146
 147 <h2><a name="download">Download</a></h2>
 148
 149 <p>The newest release is always available from <a href="http://0pointer.de/lennart/projects/libasyncns/">http://0pointer.de/lennart/projects/libasyncns/</a></p>
 150
 151 <p>The current release is <a href="http://0pointer.de/lennart/projects/libasyncns/libasyncns-0.8.tar.gz">0.8</a></p>
 152
 153 <p>Get <tt>libasyncns</tt>'s development sources from the <a href="http://git.or.cz/">GIT</a> <a href="git://git.0pointer.de/libasyncns">repository</a> (<a href="http://git.0pointer.de/?p=libasyncns.git">gitweb</a>): </p>
 154
 155 <pre>git clone git://git.0pointer.de/libasyncns</pre>
 156
 157 <p>You may find an up to date Debian package of <tt>libasyncns</tt> on the <a href="http://packages.debian.org/libasyncns0">Debian package repository</a>.</p>
 158
 159 <p>If you want to be notified whenever I release a new version of this software use the subscription feature of <a href="http://freshmeat.net/projects/libasyncns/">Freshmeat</a>.</p>
 160
 161 <hr/>
 162 <address class="grey">Lennart Poettering &lt;mznflapaf (at) 0pointer (dot) de&gt;, October 2009</address>
 163
 164 </body>
 165 </html>