diff options
Diffstat (limited to 'resolv/README')
| -rw-r--r-- | resolv/README | 74 |
1 files changed, 72 insertions, 2 deletions
diff --git a/resolv/README b/resolv/README index e862fffe57..416205da77 100644 --- a/resolv/README +++ b/resolv/README @@ -1,3 +1,6 @@ +The resolver in the GNU C Library +********************************* + Starting with version 2.2, the resolver in the GNU C Library comes from BIND 8. Only a subset of the src/lib/resolv part of libbind is included here; basically the parts that are needed to provide the @@ -30,11 +33,78 @@ The resolver in the GNU C Library still differs from what's in BIND * The `res_close' function in glibc only tries to close open files referenced through `_res' if the RES_INIT bit is set in `_res.options'. This fixes a potential security bug with programs - that bogusly call `res_close' without initializing the resolver + that bogusly call `res_close' without initialising the resolver state first. Note that the thread-safe `res_nclose' still doesn't check the RES_INIT bit. By the way, you're not really supposed to call `res_close/res_nclose' directly. +* The resolver in glibc can connect to a nameserver over IPv6. Just + specify the IPv6 address in /etc/resolv.conf. You cannot change the + address of an IPv6 nameserver dynamically in your program though. + + +Using the resolver in multi-threaded code +========================================= + +The traditional resolver interfaces `res_query', `res_search', +`res_mkquery', `res_send' and `res_init', used a static (global) +resolver state stored in the `_res' structure. Therefore, these +interfaces are not thread-safe. Therefore, BIND 8.2 introduced a set +of "new" interfaces `res_nquery', `res_nsearch', `res_nmkquery', +`res_nsend' and `res_ninit' that take a `res_state' as their first +argument, so you can use a per-thread resolver state. In glibc, when +you link with -lpthread, such a per-thread resolver state is already +present. It can be accessed using `_res', which has been redefined as +a macro, in a similar way to what has been done for the `errno' and +`h_errno' variables. This per-thread resolver state is also used for +the `gethostby*' family of functions, which means that for example +`gethostbyname_r' is now fully thread-safe and re-entrant. The +traditional resolver interfaces however, continue to use a single +resolver state and are therefore still thread-unsafe. The resolver +state is the same resolver state that is used for the initial ("main") +thread. + +This has the following consequences for existing binaries and source +code: + +* Single-threaded programs will continue to work. There should be no + user-visible changes when you recompile them. + +* Multi-threaded programs that use the traditional resolver interfaces + in the "main" thread should continue to work, except that they no + longer see any changes in the global resolver state caused by calls + to, for example, `gethostbyname' in other threads. Again there + should be no user-visible changes when you recompile these programs. + +* Multi-threaded programs that use the traditional resolver interfaces + in more than one thread should be just as buggy as before (there are + no problems if you use proper locking of course). If you recompile + these programs, manipulating the _res structure in threads other + than the "main" thread will seem to have no effect though. + +* In Multi-threaded that manipulate the _res structure, calls to + functions like `gethostbyname' in threads other than the "main" + thread won't be influenced by the those changes anymore. So if you + set RES_USE_INET6, a call to `gethostbyname' won't return any IPv6 + hosts anymore. If you recompile such programs, manipulating the + _res structure will affect the thread in which you do so instead of + the "main" thread. + +We recommend to use the new thread-safe interfaces in new code, since +the traditional interfaces have been deprecated by the BIND folks. +For compatibility with other (older) systems you might want to +continue to use those interfaces though. + + +Using the resolver in C++ code +============================== + +There resolver contains some hooks which will allow the user to +install some callback functions that make it possible to filter DNS +requests and responses. Although we do not encourage you to make use +of this facility at all, C++ developers should realise that it isn't +safe to throw exceptions from such callback functions. + Source code =========== @@ -78,7 +148,7 @@ src/lib/inet/ src/lib/isc/ base64.c -Some of these files have been optimized a bit, and adaptations have +Some of these files have been optimised a bit, and adaptations have been made to make them fit in with the rest of glibc. The more non-obvious changes are wrapped in something like `#ifdef _LIBC'. |