Back to home page

glibc Cross Reference



0001 The resolver in the GNU C Library
0002 *********************************
0004 Starting with version 2.2, the resolver in the GNU C Library comes
0005 from BIND 8.  Only a subset of the src/lib/resolv part of libbind is
0006 included here; basically the parts that are needed to provide the
0007 functionality present in the resolver from BIND 4.9.7 that was
0008 included in the previous release of the GNU C Library, augmented by
0009 the parts needed to provide thread-safety.  This means that support
0010 for things as dynamic DNS updates and TSIG keys isn't included.  If
0011 you need those facilities, please take a look at the full BIND
0012 distribution.
0015 Differences
0016 ===========
0018 The resolver in the GNU C Library still differs from what's in BIND
0019 8.2.3-T5B:
0021 * The resolver in glibc strictly adheres to the recommendations in RFC
0022   1535.  BIND 8.2.3-T5B seems to relax those rules a bit (see the code
0023   that's wrapped in `#ifndef RFC1535').
0025 * The RES_DEBUG option (`options debug' in /etc/resolv.conf) has been
0026   disabled.
0028 * The resolver in glibc allows underscores in domain names.
0030 * The <resolv.h> header in glibc includes <netinet/in.h> and
0031   <arpa/nameser.h> to make it self-contained.
0033 * The `res_close' function in glibc only tries to close open files
0034   referenced through `_res' if the RES_INIT bit is set in
0035   `_res.options'.  This fixes a potential security bug with programs
0036   that bogusly call `res_close' without initialising the resolver
0037   state first.  Note that the thread-safe `res_nclose' still doesn't
0038   check the RES_INIT bit.  By the way, you're not really supposed to
0039   call `res_close/res_nclose' directly.
0041 * The resolver in glibc can connect to a nameserver over IPv6.  Just
0042   specify the IPv6 address in /etc/resolv.conf.  You cannot change the
0043   address of an IPv6 nameserver dynamically in your program though.
0046 Using the resolver in multi-threaded code
0047 =========================================
0049 The traditional resolver interfaces `res_query', `res_search',
0050 `res_mkquery', `res_send' and `res_init', used a static (global)
0051 resolver state stored in the `_res' structure.  Therefore, these
0052 interfaces are not thread-safe.  Therefore, BIND 8.2 introduced a set
0053 of "new" interfaces `res_nquery', `res_nsearch', `res_nmkquery',
0054 `res_nsend' and `res_ninit' that take a `res_state' as their first
0055 argument, so you can use a per-thread resolver state.  In glibc, when
0056 you link with -lpthread, such a per-thread resolver state is already
0057 present.  It can be accessed using `_res', which has been redefined as
0058 a macro, in a similar way to what has been done for the `errno' and
0059 `h_errno' variables.  This per-thread resolver state is also used for
0060 the `gethostby*' family of functions, which means that for example
0061 `gethostbyname_r' is now fully thread-safe and re-entrant.  The
0062 traditional resolver interfaces however, continue to use a single
0063 resolver state and are therefore still thread-unsafe.  The resolver
0064 state is the same resolver state that is used for the initial ("main")
0065 thread.
0067 This has the following consequences for existing binaries and source
0068 code:
0070 * Single-threaded programs will continue to work.  There should be no
0071   user-visible changes when you recompile them.
0073 * Multi-threaded programs that use the traditional resolver interfaces
0074   in the "main" thread should continue to work, except that they no
0075   longer see any changes in the global resolver state caused by calls
0076   to, for example, `gethostbyname' in other threads.  Again there
0077   should be no user-visible changes when you recompile these programs.
0079 * Multi-threaded programs that use the traditional resolver interfaces
0080   in more than one thread should be just as buggy as before (there are
0081   no problems if you use proper locking of course).  If you recompile
0082   these programs, manipulating the _res structure in threads other
0083   than the "main" thread will seem to have no effect though.
0085 * In Multi-threaded that manipulate the _res structure, calls to
0086   functions like `gethostbyname' in threads other than the "main"
0087   thread won't be influenced by the those changes anymore.  So if you
0088   set RES_USE_INET6, a call to `gethostbyname' won't return any IPv6
0089   hosts anymore.  If you recompile such programs, manipulating the
0090   _res structure will affect the thread in which you do so instead of
0091   the "main" thread.
0093 We recommend to use the new thread-safe interfaces in new code, since
0094 the traditional interfaces have been deprecated by the BIND folks.
0095 For compatibility with other (older) systems you might want to
0096 continue to use those interfaces though.
0099 Using the resolver in C++ code
0100 ==============================
0102 There resolver contains some hooks which will allow the user to
0103 install some callback functions that make it possible to filter DNS
0104 requests and responses.  Although we do not encourage you to make use
0105 of this facility at all, C++ developers should realise that it isn't
0106 safe to throw exceptions from such callback functions.
0109 Source code
0110 ===========
0112 The following files come from the BIND distribution (currently version
0113 8.2.3-T5B):
0115 src/include/
0116   arpa/nameser.h
0117   arpa/nameser_compat.h
0118   resolv.h
0120 src/lib/resolv/
0121   herror.c
0122   res_comp.c
0123   res_data.c
0124   res_debug.c
0125   res_debug.h
0126   res_init.c
0127   res_mkquery.c
0128   res_query.c
0129   res_send.c
0131 src/lib/nameser/
0132   ns_name.c
0133   ns_netint.c
0134   ns_parse.c
0135   ns_print.c
0136   ns_samedomain.c
0137   ns_ttl.c
0139 src/lib/inet/
0140   inet_addr.c
0141   inet_net_ntop.c
0142   inet_net_pton.c
0143   inet_neta.c
0144   inet_ntop.c
0145   inet_pton.c
0146   nsap_addr.c
0148 src/lib/isc/
0149   base64.c
0151 Some of these files have been optimised a bit, and adaptations have
0152 been made to make them fit in with the rest of glibc.  The more
0153 non-obvious changes are wrapped in something like `#ifdef _LIBC'.
0155 res_libc.c is home-brewn, although parts of it are taken from res_data.c.
0157 res_hconf.c and res_hconf.h were contributed by David Mosberger, and
0158 do not come from BIND.
0160 The files gethnamaddr.c, mapv4v6addr.h and mapv4v6hostent.h are
0161 leftovers from BIND 4.9.7.