From 44e4b889ab0e0497567c8983ad25a78798a3ab51 Mon Sep 17 00:00:00 2001 From: Florian Weimer Date: Fri, 21 Apr 2017 10:28:37 +0200 Subject: manual: Document replacing malloc [BZ #20424] --- ChangeLog | 7 ++++++ manual/memory.texi | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) diff --git a/ChangeLog b/ChangeLog index e60f6c3469..dedd753d5f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2017-04-21 Florian Weimer + + [BZ #20424] + * manual/memory.texi (Replacing malloc): New section. + (Allocating Storage For Program Data): Reference it. + (The GNU Allocator): Likewise. + 2017-04-20 Joseph Myers * stdlib/Versions (__strtod_internal): List explicitly, not as diff --git a/manual/memory.texi b/manual/memory.texi index a39cac805f..a256ca07b2 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 @uref{https://sourceware.org/glibc/wiki/MallocInternals}. +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} +function. + +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 -- cgit v1.2.1