1The resolver in the GNU C Library
2*********************************
3
4Starting with version 2.2, the resolver in the GNU C Library comes
5from BIND 8.  Only a subset of the src/lib/resolv part of libbind is
6included here; basically the parts that are needed to provide the
7functionality present in the resolver from BIND 4.9.7 that was
8included in the previous release of the GNU C Library, augmented by
9the parts needed to provide thread-safety.  This means that support
10for things as dynamic DNS updates and TSIG keys isn't included.  If
11you need those facilities, please take a look at the full BIND
12distribution.
13
14
15Differences
16===========
17
18The resolver in the GNU C Library still differs from what's in BIND
198.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
42Using the resolver in multi-threaded code
43=========================================
44
45The traditional resolver interfaces `res_query', `res_search',
46`res_mkquery', `res_send' and `res_init', used a static (global)
47resolver state stored in the `_res' structure.  Therefore, these
48interfaces are not thread-safe.  Therefore, BIND 8.2 introduced a set
49of "new" interfaces `res_nquery', `res_nsearch', `res_nmkquery',
50`res_nsend' and `res_ninit' that take a `res_state' as their first
51argument, so you can use a per-thread resolver state.  In glibc, when
52you link with -lpthread, such a per-thread resolver state is already
53present.  It can be accessed using `_res', which has been redefined as
54a 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
56the `gethostby*' family of functions, which means that for example
57`gethostbyname_r' is now fully thread-safe and re-entrant.  The
58traditional resolver interfaces however, continue to use a single
59resolver state and are therefore still thread-unsafe.  The resolver
60state is the same resolver state that is used for the initial ("main")
61thread.
62
63This has the following consequences for existing binaries and source
64code:
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
85We recommend to use the new thread-safe interfaces in new code, since
86the traditional interfaces have been deprecated by the BIND folks.
87For compatibility with other (older) systems you might want to
88continue to use those interfaces though.
89
90
91Using the resolver in C++ code
92==============================
93
94There resolver contains some hooks which will allow the user to
95install some callback functions that make it possible to filter DNS
96requests and responses.  Although we do not encourage you to make use
97of this facility at all, C++ developers should realise that it isn't
98safe to throw exceptions from such callback functions.
99
100
101Source code
102===========
103
104The following files come from the BIND distribution (currently version
1058.2.3-T5B):
106
107src/include/
108  arpa/nameser.h
109  arpa/nameser_compat.h
110  resolv.h
111
112src/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
122src/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
130src/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
139src/lib/isc/
140  base64.c
141
142Some of these files have been optimised a bit, and adaptations have
143been made to make them fit in with the rest of glibc.
144
145res_libc.c is home-brewn, although parts of it are taken from res_data.c.
146
147res_hconf.c and res_hconf.h were contributed by David Mosberger, and
148do not come from BIND.
149
150The files gethnamaddr.c, mapv4v6addr.h and mapv4v6hostent.h are
151leftovers from BIND 4.9.7.
152