README

   1 This is c-ares, a forked version of the original ares. The original ares
   2 README follows below, the c-ares specific details are in README.cares
   3
   4 ====================================================================
   5
   6 This is ares, an asynchronous resolver library.  It is intended for
   7 applications which need to perform DNS queries without blocking, or
   8 need to perform multiple DNS queries in parallel.  The primary
   9 examples of such applications are servers which communicate with
  10 multiple clients and programs with graphical user interfaces.
  11
  12 This library implementation is not especially portable to crufty old
  13 systems like SunOS 4.  It assumes a compiler which can handle ANSI C
  14 syntax, a system malloc which properly handles realloc(NULL, foo) and
  15 free(NULL), and a reasonably up-to-date <arpa/nameser.h>.
  16
  17 I have attempted to preserve the externally visible behavior of the
  18 BIND resolver in nearly all respects.  The API of the library is, of
  19 course, very different from the synchronous BIND API; instead of
  20 invoking a function like res_send() and getting a return value back
  21 indicating the number of bytes in the response, you invoke a function
  22 like ares_send() and give it a callback function to invoke when the
  23 response arrives.  You then have to select() on the file descriptors
  24 indicated by ares_fds(), with a timeout given by ares_timeout().  You
  25 call ares_process() when select() returns.
  26
  27 Some features are missing from the current version of ares, relative
  28 to the BIND resolver:
  29
  30         * There is no IPV6 support.                [not true for c-ares]
  31         * There is no hostname verification.
  32         * There is no logging of unexpected events.
  33         * There is no debugging-oriented logging.
  34         * There is no YP support.
  35
  36 libares requires an ANSI compiler to compile and use.  To build the
  37 library, just run "./configure" and "make".  To install it, run "make
  38 install".  Run "./configure --help" to see a list of options you can
  39 provide to configure to change how the library builds.  libares has no
  40 data files, so you can move the include file and library around freely
  41 without leaving behind any dependencies on old paths.  Building the
  42 library will also build the "adig" program, a little toy for trying
  43 out the library.  It doesn't get installed.
  44
  45 libares is distributed at athena-dist.mit.edu:pub/ATHENA/ares.  Please
  46 send bug reports and comments to ghudson@mit.edu.