"Fossies" - the Fresh Open Source Software Archive

Member "glibc-2.36/resolv/README" (29 Jul 2022, 5430 Bytes) of package /linux/misc/glibc-2.36.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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.
   84 
   85 We recommend to use the new thread-safe interfaces in new code, since
   86 the traditional interfaces have been deprecated by the BIND folks.
   87 For compatibility with other (older) systems you might want to
   88 continue to use those interfaces though.
   89 
   90 
   91 Using the resolver in C++ code
   92 ==============================
   93 
   94 There resolver contains some hooks which will allow the user to
   95 install some callback functions that make it possible to filter DNS
   96 requests and responses.  Although we do not encourage you to make use
   97 of this facility at all, C++ developers should realise that it isn't
   98 safe to throw exceptions from such callback functions.
   99 
  100 
  101 Source code
  102 ===========
  103 
  104 The following files come from the BIND distribution (currently version
  105 8.2.3-T5B):
  106 
  107 src/include/
  108   arpa/nameser.h
  109   arpa/nameser_compat.h
  110   resolv.h
  111 
  112 src/lib/resolv/
  113   herror.c
  114   res_comp.c
  115   res_data.c
  116   res_debug.c
  117   res_init.c
  118   res_mkquery.c
  119   res_query.c
  120   res_send.c
  121 
  122 src/lib/nameser/
  123   ns_name.c
  124   ns_netint.c
  125   ns_parse.c
  126   ns_print.c
  127   ns_samedomain.c
  128   ns_ttl.c
  129 
  130 src/lib/inet/
  131   inet_addr.c
  132   inet_net_ntop.c
  133   inet_net_pton.c
  134   inet_neta.c
  135   inet_ntop.c
  136   inet_pton.c
  137   nsap_addr.c
  138 
  139 src/lib/isc/
  140   base64.c
  141 
  142 Some of these files have been optimised a bit, and adaptations have
  143 been made to make them fit in with the rest of glibc.
  144 
  145 res_libc.c is home-brewn, although parts of it are taken from res_data.c.
  146 
  147 res_hconf.c and res_hconf.h were contributed by David Mosberger, and
  148 do not come from BIND.
  149 
  150 The files gethnamaddr.c, mapv4v6addr.h and mapv4v6hostent.h are
  151 leftovers from BIND 4.9.7.