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