Replacing malloc (The GNU C Library)

#### 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 `malloc` should return a null pointer only when failing, it should return pointers aligned to `alignof (max_align_t)`, and the replacement `free` should 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.1

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`
`free_aligned_sized`
`free_sized`
`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.

#### Footnotes

##### (1)

Versions of the GNU C Library before 2.25 required that a custom `malloc` defines `__libc_memalign` (with the same interface as the `memalign` function).