blob: dbb15108ae025e2896c0dc1d9161f14d6e05d330 [file] [log] [blame]
lh9ed821d2023-04-07 01:36:19 -07001The 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 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
46Using the resolver in multi-threaded code
47=========================================
48
49The traditional resolver interfaces `res_query', `res_search',
50`res_mkquery', `res_send' and `res_init', used a static (global)
51resolver state stored in the `_res' structure. Therefore, these
52interfaces are not thread-safe. Therefore, BIND 8.2 introduced a set
53of "new" interfaces `res_nquery', `res_nsearch', `res_nmkquery',
54`res_nsend' and `res_ninit' that take a `res_state' as their first
55argument, so you can use a per-thread resolver state. In glibc, when
56you link with -lpthread, such a per-thread resolver state is already
57present. It can be accessed using `_res', which has been redefined as
58a 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
60the `gethostby*' family of functions, which means that for example
61`gethostbyname_r' is now fully thread-safe and re-entrant. The
62traditional resolver interfaces however, continue to use a single
63resolver state and are therefore still thread-unsafe. The resolver
64state is the same resolver state that is used for the initial ("main")
65thread.
66
67This has the following consequences for existing binaries and source
68code:
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
93We recommend to use the new thread-safe interfaces in new code, since
94the traditional interfaces have been deprecated by the BIND folks.
95For compatibility with other (older) systems you might want to
96continue to use those interfaces though.
97
98
99Using the resolver in C++ code
100==============================
101
102There resolver contains some hooks which will allow the user to
103install some callback functions that make it possible to filter DNS
104requests and responses. Although we do not encourage you to make use
105of this facility at all, C++ developers should realise that it isn't
106safe to throw exceptions from such callback functions.
107
108
109Source code
110===========
111
112The following files come from the BIND distribution (currently version
1138.2.3-T5B):
114
115src/include/
116 arpa/nameser.h
117 arpa/nameser_compat.h
118 resolv.h
119
120src/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
131src/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
139src/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
148src/lib/isc/
149 base64.c
150
151Some of these files have been optimised a bit, and adaptations have
152been made to make them fit in with the rest of glibc. The more
153non-obvious changes are wrapped in something like `#ifdef _LIBC'.
154
155res_libc.c is home-brewn, although parts of it are taken from res_data.c.
156
157res_hconf.c and res_hconf.h were contributed by David Mosberger, and
158do not come from BIND.
159
160The files gethnamaddr.c, mapv4v6addr.h and mapv4v6hostent.h are
161leftovers from BIND 4.9.7.