]>
Commit | Line | Data |
---|---|---|
497b8ef4 UD |
1 | The resolver in the GNU C Library |
2 | ********************************* | |
3 | ||
4e8286ac UD |
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 | ||
4e8286ac UD |
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 | |
497b8ef4 | 32 | that bogusly call `res_close' without initialising the resolver |
4e8286ac UD |
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 | ||
497b8ef4 UD |
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") | |
9c84384c | 61 | thread. |
497b8ef4 UD |
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" | |
b76e0659 | 83 | thread won't be influenced by the those changes anymore. |
497b8ef4 UD |
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 | ||
4e8286ac UD |
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 | |
4e8286ac UD |
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 | ||
497b8ef4 | 142 | Some of these files have been optimised a bit, and adaptations have |
c99c925b | 143 | been made to make them fit in with the rest of glibc. |
4e8286ac UD |
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. |