document usage of BIND9 constructors/destructors

Document the way `__attribute__((__constructor__))` and
`__attribute__((__destructor__))` must be used in BIND9 libraries in
order to avoid unexpected behaviors with other third-party libraries.

diff --git a/lib/dns/include/dns/lib.h b/lib/dns/include/dns/lib.h
index cb88744bbebf4edc7e4cd4190ac0796b50529cff..9cf053a7c2c401013def698ac686ccc28c41991a 100644 (file)
--- a/lib/dns/include/dns/lib.h
+++ b/lib/dns/include/dns/lib.h
@@ -11,6 +11,10 @@
  * information regarding copyright ownership.
  */
 
+/*
+ * See `lib/isc/include/isc/lib.h` README
+ */
+
 #pragma once
 
 #include <stdlib.h>

diff --git a/lib/isc/include/isc/lib.h b/lib/isc/include/isc/lib.h
index ee918e7899ae34c30fe59ba3e78f90c53eb17b24..412dd9746d283f2c0be29932fe1ddc8df5a1a4ff 100644 (file)
--- a/lib/isc/include/isc/lib.h
+++ b/lib/isc/include/isc/lib.h
@@ -11,6 +11,34 @@
  * information regarding copyright ownership.
  */
 
+/*
+ * BIND9 constructor/destructor README
+ * -----------------------------------
+ *
+ * A function tagged with `__attribute__((__destructor__))` is called right
+ * after `main()` returns (or `exit()` is called; see `man atexit` for more
+ * details). However is a valid assumption _only_ if the function is defined
+ * inside the binary.
+ *
+ * If the function is defined as part of a shared library, it will
+ * be called only when the library is unloaded by the OS linker. There is no
+ * way to control the order in which two destructor functions "A" and "B" are
+ * called if they are defined in separate libraries, because it depends
+ * on the order in which the OS linker unloads the libraries.
+ *
+ * As a consequence, all contructor/destructor functions of BIND9 must be
+ * defined in `lib/<lib>/include/<lib>/lib.h` header and such header must be
+ * included in each binaries (in each C file defining `main()`) and must not be
+ * included in any library.
+ *
+ * Otherwise, there might be interference. For example, LSAN which could run
+ * before the BIND9 destructor functions have cleaned up remaining non-root
+ * memory.
+ *
+ * The order of the calls between the BIND9 constructors/destructors is enforced
+ * by a reference counter in the `<lib>__lib_{initialize,shutdown}` functions.
+ */
+
 #pragma once
 
 #include <isc/util.h>