resolv/README

   1 The resolver in the GNU C Library
   2 *********************************
   3
   4 Starting with version 2.2, the resolver in the GNU C Library comes
   5 from BIND 8.  Only a subset of the src/lib/resolv part of libbind is
   6 included here; basically the parts that are needed to provide the
   7 functionality present in the resolver from BIND 4.9.7 that was
   8 included in the previous release of the GNU C Library, augmented by
   9 the parts needed to provide thread-safety.  This means that support
  10 for things as dynamic DNS updates and TSIG keys isn't included.  If
  11 you need those facilities, please take a look at the full BIND
  12 distribution.
  13
  14
  15 Differences
  16 ===========
  17
  18 The resolver in the GNU C Library still differs from what's in BIND
  19 8.2.3-T5B:
  20
  21 * The RES_DEBUG option (`options debug' in /etc/resolv.conf) has been
  22   disabled.
  23
  24 * The resolver in glibc allows underscores in domain names.
  25
  26 * The <resolv.h> header in glibc includes <netinet/in.h> and
  27   <arpa/nameser.h> to make it self-contained.
  28
  29 * The `res_close' function in glibc only tries to close open files
  30   referenced through `_res' if the RES_INIT bit is set in
  31   `_res.options'.  This fixes a potential security bug with programs
  32   that bogusly call `res_close' without initialising the resolver
  33   state first.  Note that the thread-safe `res_nclose' still doesn't
  34   check the RES_INIT bit.  By the way, you're not really supposed to
  35   call `res_close/res_nclose' directly.
  36
  37 * The resolver in glibc can connect to a nameserver over IPv6.  Just
  38   specify the IPv6 address in /etc/resolv.conf.  You cannot change the
  39   address of an IPv6 nameserver dynamically in your program though.
  40
  41
  42 Using the resolver in multi-threaded code
  43 =========================================
  44
  45 The traditional resolver interfaces `res_query', `res_search',
  46 `res_mkquery', `res_send' and `res_init', used a static (global)
  47 resolver state stored in the `_res' structure.  Therefore, these
  48 interfaces are not thread-safe.  Therefore, BIND 8.2 introduced a set
  49 of "new" interfaces `res_nquery', `res_nsearch', `res_nmkquery',
  50 `res_nsend' and `res_ninit' that take a `res_state' as their first
  51 argument, so you can use a per-thread resolver state.  In glibc, when
  52 you link with -lpthread, such a per-thread resolver state is already
  53 present.  It can be accessed using `_res', which has been redefined as
  54 a macro, in a similar way to what has been done for the `errno' and
  55 `h_errno' variables.  This per-thread resolver state is also used for
  56 the `gethostby*' family of functions, which means that for example
  57 `gethostbyname_r' is now fully thread-safe and re-entrant.  The
  58 traditional resolver interfaces however, continue to use a single
  59 resolver state and are therefore still thread-unsafe.  The resolver
  60 state is the same resolver state that is used for the initial ("main")
  61 thread.
  62
  63 This has the following consequences for existing binaries and source
  64 code:
  65
  66 * Single-threaded programs will continue to work.  There should be no
  67   user-visible changes when you recompile them.
  68
  69 * Multi-threaded programs that use the traditional resolver interfaces
  70   in the "main" thread should continue to work, except that they no
  71   longer see any changes in the global resolver state caused by calls
  72   to, for example, `gethostbyname' in other threads.  Again there
  73   should be no user-visible changes when you recompile these programs.
  74
  75 * Multi-threaded programs that use the traditional resolver interfaces
  76   in more than one thread should be just as buggy as before (there are
  77   no problems if you use proper locking of course).  If you recompile
  78   these programs, manipulating the _res structure in threads other
  79   than the "main" thread will seem to have no effect though.
  80
  81 * In Multi-threaded that manipulate the _res structure, calls to
  82   functions like `gethostbyname' in threads other than the "main"
  83   thread won't be influenced by the those changes anymore.  So if you
  84   set RES_USE_INET6, a call to `gethostbyname' won't return any IPv6
  85   hosts anymore.  If you recompile such programs, manipulating the
  86   _res structure will affect the thread in which you do so instead of
  87   the "main" thread.
  88
  89 We recommend to use the new thread-safe interfaces in new code, since
  90 the traditional interfaces have been deprecated by the BIND folks.
  91 For compatibility with other (older) systems you might want to
  92 continue to use those interfaces though.
  93
  94
  95 Using the resolver in C++ code
  96 ==============================
  97
  98 There resolver contains some hooks which will allow the user to
  99 install some callback functions that make it possible to filter DNS
 100 requests and responses.  Although we do not encourage you to make use
 101 of this facility at all, C++ developers should realise that it isn't
 102 safe to throw exceptions from such callback functions.
 103
 104
 105 Source code
 106 ===========
 107
 108 The following files come from the BIND distribution (currently version
 109 8.2.3-T5B):
 110
 111 src/include/
 112   arpa/nameser.h
 113   arpa/nameser_compat.h
 114   resolv.h
 115
 116 src/lib/resolv/
 117   herror.c
 118   res_comp.c
 119   res_data.c
 120   res_debug.c
 121   res_debug.h
 122   res_init.c
 123   res_mkquery.c
 124   res_query.c
 125   res_send.c
 126
 127 src/lib/nameser/
 128   ns_name.c
 129   ns_netint.c
 130   ns_parse.c
 131   ns_print.c
 132   ns_samedomain.c
 133   ns_ttl.c
 134
 135 src/lib/inet/
 136   inet_addr.c
 137   inet_net_ntop.c
 138   inet_net_pton.c
 139   inet_neta.c
 140   inet_ntop.c
 141   inet_pton.c
 142   nsap_addr.c
 143
 144 src/lib/isc/
 145   base64.c
 146
 147 Some of these files have been optimised a bit, and adaptations have
 148 been made to make them fit in with the rest of glibc.
 149
 150 res_libc.c is home-brewn, although parts of it are taken from res_data.c.
 151
 152 res_hconf.c and res_hconf.h were contributed by David Mosberger, and
 153 do not come from BIND.
 154
 155 The files gethnamaddr.c, mapv4v6addr.h and mapv4v6hostent.h are
 156 leftovers from BIND 4.9.7.