---

3.2.5 Replacing malloc ¶

The GNU C Library supports replacing the built-in 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 LD_PRELOAD. For static linking, the malloc replacement library must be linked in before linking against libc.a (explicitly or implicitly).

Care must be taken not to use functionality from the GNU C Library that uses malloc internally. For example, the fopen, opendir, dlopen, and pthread_setspecific functions currently use the malloc subsystem internally. If the replacement malloc or its dependencies use thread-local storage (TLS), it must use the initial-exec TLS model, and not one of the dynamic TLS variants.

Note: Failure to provide a complete set of replacement functions (that is, all the functions used by the application, the GNU C Library, and other linked-in libraries) can lead to static linking failures, and, at run time, to heap corruption and application crashes. Replacement functions should implement the behavior documented for their counterparts in the GNU C Library; for example, the replacement free should also preserve errno.

The minimum set of functions which has to be provided by a custom malloc is given in the table below.

malloc

free

calloc

realloc

These malloc-related functions are required for the GNU C Library to work.¹

The malloc implementation in the GNU C Library provides additional functionality not used by the library itself, but which is often used by other system libraries and applications. A general-purpose replacement malloc implementation should provide definitions of these functions, too. Their names are listed in the following table.

aligned_alloc

malloc_usable_size

memalign

posix_memalign

pvalloc

valloc

In addition, very old applications may use the obsolete cfree function.

Further malloc-related functions such as mallopt or mallinfo2 will not have any effect or return incorrect statistics when a replacement 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.

There are other functions (reallocarray, strdup, etc.) in the GNU C Library that are not listed above but return newly allocated memory to callers. Replacement of these functions is not supported and may produce incorrect results. The GNU C Library implementations of these functions call the replacement allocator functions whenever available, so they will work correctly with malloc replacement.