path: root/manual/memory.texi
diff options
authorFlorian Weimer <fweimer@redhat.com>2017-04-21 10:28:37 +0200
committerFlorian Weimer <fweimer@redhat.com>2017-04-21 10:28:37 +0200
commit44e4b889ab0e0497567c8983ad25a78798a3ab51 (patch)
tree7c85362cc333f6e966e9984e73e31abd51e373b8 /manual/memory.texi
parent832d8bc00b66adcb98a1c2064a2d555853ea49ed (diff)
manual: Document replacing malloc [BZ #20424]
Diffstat (limited to 'manual/memory.texi')
1 files changed, 65 insertions, 0 deletions
diff --git a/manual/memory.texi b/manual/memory.texi
index a39cac805f8..a256ca07b2b 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -167,6 +167,7 @@ special to @theglibc{} and GNU Compiler.
* Unconstrained Allocation:: The @code{malloc} facility allows fully general
dynamic allocation.
* Allocation Debugging:: Finding memory leaks and not freed memory.
+* Replacing malloc:: Using your own @code{malloc}-style allocator.
* Obstacks:: Obstacks are less general than malloc
but more efficient and convenient.
* Variable Size Automatic:: Allocation of variable-sized blocks
@@ -299,6 +300,9 @@ A more detailed technical description of the GNU Allocator is maintained in
the @glibcadj{} wiki. See
+It is possible to use your own custom @code{malloc} instead of the
+built-in allocator provided by @theglibc{}. @xref{Replacing malloc}.
@node Unconstrained Allocation
@subsection Unconstrained Allocation
@cindex unconstrained memory allocation
@@ -1898,6 +1902,67 @@ from line 33 in the source file @file{/home/drepper/tst-mtrace.c} four
times without freeing this memory before the program terminates.
Whether this is a real problem remains to be investigated.
+@node Replacing malloc
+@subsection Replacing @code{malloc}
+@cindex @code{malloc} replacement
+@cindex @code{LD_PRELOAD} and @code{malloc}
+@cindex alternative @code{malloc} implementations
+@cindex customizing @code{malloc}
+@cindex interposing @code{malloc}
+@cindex preempting @code{malloc}
+@cindex replacing @code{malloc}
+@Theglibc{} supports replacing the built-in @code{malloc} implementation
+with a different allocator with the same interface. For dynamically
+linked programs, this happens through ELF symbol interposition, either
+using shared object dependencies or @code{LD_PRELOAD}. For static
+linking, the @code{malloc} replacement library must be linked in before
+linking against @code{libc.a} (explicitly or implicitly).
+@strong{Note:} Failure to provide a complete set of replacement
+functions (that is, all the functions used by the application,
+@theglibc{}, and other linked-in libraries) can lead to static linking
+failures, and, at run time, to heap corruption and application crashes.
+The minimum set of functions which has to be provided by a custom
+@code{malloc} is given in the table below.
+@table @code
+@item malloc
+@item free
+@item calloc
+@item realloc
+@end table
+These @code{malloc}-related functions are required for @theglibc{} to
+work.@footnote{Versions of @theglibc{} before 2.25 required that a
+custom @code{malloc} defines @code{__libc_memalign} (with the same
+interface as the @code{memalign} function).}
+The @code{malloc} implementation in @theglibc{} provides additional
+functionality not used by the library itself, but which is often used by
+other system libraries and applications. A general-purpose replacement
+@code{malloc} implementation should provide definitions of these
+functions, too. Their names are listed in the following table.
+@table @code
+@item aligned_alloc
+@item malloc_usable_size
+@item memalign
+@item posix_memalign
+@item pvalloc
+@item valloc
+@end table
+In addition, very old applications may use the obsolete @code{cfree}
+Further @code{malloc}-related functions such as @code{mallopt} or
+@code{mallinfo} will not have any effect or return incorrect statistics
+when a replacement @code{malloc} is in use. However, failure to replace
+these functions typically does not result in crashes or other incorrect
+application behavior, but may result in static linking failures.
@node Obstacks
@subsection Obstacks
@cindex obstacks