1 files changed, 43 insertions, 0 deletions
diff --git a/linker/README.TXT b/linker/README.TXT
index 4fff14e..0be9be4 100644
--- a/linker/README.TXT
+++ b/linker/README.TXT
@@ -112,3 +112,46 @@ On x86, the lists of constructors and destructors are placed in special
 sections named ".ctors" and ".dtors", and the DT_INIT / DT_FINI functions
 are in charge of calling them explicitely.
 
+
+C Library Usage Restrictions:
+-----------------------------
+
+The dynamic linker executable (/system/bin/linker) is built using the
+static version of the C library (libc.a), in order to use various functions
+and system calls provided by it.
+
+However, it will normally, at runtime, map the shared library version
+of the C library (/system/lib/libc.so) as well in the process' address
+space. This means that:
+
+- any global variable defined by the C library will appear twice in
+  the process address space, at different addresses.
+
+- some functions will be duplicated too, though those that refer to
+  global variables will refer to distinct addresses.
+
+This can lead to subtle conflicts, typically for process-specific data that
+is managed through the kernel. A good example is the handling of the
+end of the data segment, which is normally done through the 'sbrk' or
+'brk' system call by the malloc implementation.
+
+If two similar, but distinct, malloc implementations run at the same time,
+and if each one thinks it exclusively manages some process settings, hideous
+corruption or crashes may occur.
+
+For this very reason, THE DYNAMIC LINKER CANNOT USE malloc()/free() !
+That's why it is linked to a special version of the C library that will
+abort when any of these functions (or calloc()/realloc()) is called.
+
+Moreover, it cannot use any C library feature that could use these
+indirectly. Experience as shown that this meant:
+
+- avoiding any FILE* - related stdio function (fopen, fread, fprintf, etc...)
+- avoiding snprintf() with any floating-point formatter ("%f", "%g")
+
+There are probably other cases that haven't been discovered yet, so the
+code needs to be very frugal in its use of the C library.
+
+This also explains why the linker's tracing macros are all disabled by
+default. Enabling them sometimes creates problems, depending on the process
+being loaded, so they should be considered an experimental feature for now.