More stuff
[kopensolaris-gnu/glibc.git] / 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 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.