"Fossies" - the Fresh Open Source Software Archive 
Member "glibc-2.38/resolv/README" (31 Jul 2023, 5338 Bytes) of package /linux/misc/glibc-2.38.tar.xz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the last
Fossies "Diffs" side-by-side code changes report for "README":
2.36_vs_2.37.
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 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
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")
61 thread.
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"
83 thread won't be influenced by the those changes anymore.
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
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
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
142 Some of these files have been optimised a bit, and adaptations have
143 been made to make them fit in with the rest of glibc.
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.