mallopt(3) Library Functions Manual mallopt(3)
NAME
mallopt - set memory allocation parameters
LIBRARY
Standard C library (libc, -lc)
SYNOPSIS
#include <malloc.h>
int mallopt(int param, int value);
DESCRIPTION
The mallopt() function adjusts parameters that control the behavior of
the memory-allocation functions (see malloc(3)). The param argument
specifies the parameter to be modified, and value specifies the new
value for that parameter.
The following values can be specified for param:
M_ARENA_MAX
If this parameter has a nonzero value, it defines a hard limit on
the maximum number of arenas that can be created. An arena rep-
resents a pool of memory that can be used by malloc(3) (and simi-
lar) calls to service allocation requests. Arenas are thread
safe and therefore may have multiple concurrent memory requests.
The trade-off is between the number of threads and the number of
arenas. The more arenas you have, the lower the per-thread con-
tention, but the higher the memory usage.
The default value of this parameter is 0, meaning that the limit
on the number of arenas is determined according to the setting of
M_ARENA_TEST.
This parameter has been available since glibc 2.10 via --en-
able-experimental-malloc, and since glibc 2.15 by default. In
some versions of the allocator there was no limit on the number
of created arenas (e.g., CentOS 5, RHEL 5).
When employing newer glibc versions, applications may in some
cases exhibit high contention when accessing arenas. In these
cases, it may be beneficial to increase M_ARENA_MAX to match the
number of threads. This is similar in behavior to strategies
taken by tcmalloc and jemalloc (e.g., per-thread allocation
pools).
M_ARENA_TEST
This parameter specifies a value, in number of arenas created, at
which point the system configuration will be examined to deter-
mine a hard limit on the number of created arenas. (See
M_ARENA_MAX for the definition of an arena.)
The computation of the arena hard limit is implementation-defined
and is usually calculated as a multiple of the number of avail-
able CPUs. Once the hard limit is computed, the result is final
and constrains the total number of arenas.
The default value for the M_ARENA_TEST parameter is 2 on systems
where sizeof(long) is 4; otherwise the default value is 8.
This parameter has been available since glibc 2.10 via --en-
able-experimental-malloc, and since glibc 2.15 by default.
The value of M_ARENA_TEST is not used when M_ARENA_MAX has a
nonzero value.
M_CHECK_ACTION
Setting this parameter controls how glibc responds when various
kinds of programming errors are detected (e.g., freeing the same
pointer twice). The 3 least significant bits (2, 1, and 0) of
the value assigned to this parameter determine the glibc behav-
ior, as follows:
Bit 0 If this bit is set, then print a one-line message on
stderr that provides details about the error. The message
starts with the string "*** glibc detected ***", followed
by the program name, the name of the memory-allocation
function in which the error was detected, a brief descrip-
tion of the error, and the memory address where the error
was detected.
Bit 1 If this bit is set, then, after printing any error message
specified by bit 0, the program is terminated by calling
abort(3). Since glibc 2.4, if bit 0 is also set, then,
between printing the error message and aborting, the pro-
gram also prints a stack trace in the manner of back-
trace(3), and prints the process's memory mapping in the
style of /proc/pid/maps (see proc(5)).
Bit 2 (since glibc 2.4)
This bit has an effect only if bit 0 is also set. If this
bit is set, then the one-line message describing the error
is simplified to contain just the name of the function
where the error was detected and the brief description of
the error.
The remaining bits in value are ignored.
Combining the above details, the following numeric values are
meaningful for M_CHECK_ACTION:
0 Ignore error conditions; continue execution (with un-
defined results).
1 Print a detailed error message and continue execu-
tion.
2 Abort the program.
3 Print detailed error message, stack trace, and memory
mappings, and abort the program.
5 Print a simple error message and continue execution.
7 Print simple error message, stack trace, and memory
mappings, and abort the program.
Since glibc 2.3.4, the default value for the M_CHECK_ACTION para-
meter is 3. In glibc 2.3.3 and earlier, the default value is 1.
Using a nonzero M_CHECK_ACTION value can be useful because other-
wise a crash may happen much later, and the true cause of the
problem is then very hard to track down.
M_MMAP_MAX
This parameter specifies the maximum number of allocation re-
quests that may be simultaneously serviced using mmap(2). This
parameter exists because some systems have a limited number of
internal tables for use by mmap(2), and using more than a few of
them may degrade performance.
The default value is 65,536, a value which has no special signif-
icance and which serves only as a safeguard. Setting this para-
meter to 0 disables the use of mmap(2) for servicing large allo-
cation requests.
M_MMAP_THRESHOLD
For allocations greater than or equal to the limit specified (in
bytes) by M_MMAP_THRESHOLD that can't be satisfied from the free
list, the memory-allocation functions employ mmap(2) instead of
increasing the program break using sbrk(2).
Allocating memory using mmap(2) has the significant advantage
that the allocated memory blocks can always be independently re-
leased back to the system. (By contrast, the heap can be trimmed
only if memory is freed at the top end.) On the other hand,
there are some disadvantages to the use of mmap(2): deallocated
space is not placed on the free list for reuse by later alloca-
tions; memory may be wasted because mmap(2) allocations must be
page-aligned; and the kernel must perform the expensive task of
zeroing out memory allocated via mmap(2). Balancing these fac-
tors leads to a default setting of 128*1024 for the
M_MMAP_THRESHOLD parameter.
The lower limit for this parameter is 0. The upper limit is DE-
FAULT_MMAP_THRESHOLD_MAX: 512*1024 on 32-bit systems or
4*1024*1024*sizeof(long) on 64-bit systems.
Note: Nowadays, glibc uses a dynamic mmap threshold by default.
The initial value of the threshold is 128*1024, but when blocks
larger than the current threshold and less than or equal to DE-
FAULT_MMAP_THRESHOLD_MAX are freed, the threshold is adjusted up-
ward to the size of the freed block. When dynamic mmap thresh-
olding is in effect, the threshold for trimming the heap is also
dynamically adjusted to be twice the dynamic mmap threshold. Dy-
namic adjustment of the mmap threshold is disabled if any of the
M_TRIM_THRESHOLD, M_TOP_PAD, M_MMAP_THRESHOLD, or M_MMAP_MAX pa-
rameters is set.
M_MXFAST (since glibc 2.3)
Set the upper limit for memory allocation requests that are sat-
isfied using "fastbins". (The measurement unit for this parame-
ter is bytes.) Fastbins are storage areas that hold deallocated
blocks of memory of the same size without merging adjacent free
blocks. Subsequent reallocation of blocks of the same size can
be handled very quickly by allocating from the fastbin, although
memory fragmentation and the overall memory footprint of the pro-
gram can increase.
The default value for this parameter is 64*sizeof(size_t)/4
(i.e., 64 on 32-bit architectures). The range for this parameter
is 0 to 80*sizeof(size_t)/4. Setting M_MXFAST to 0 disables the
use of fastbins.
M_PERTURB (since glibc 2.4)
If this parameter is set to a nonzero value, then bytes of allo-
cated memory (other than allocations via calloc(3)) are initial-
ized to the complement of the value in the least significant byte
of value, and when allocated memory is released using free(3),
the freed bytes are set to the least significant byte of value.
This can be useful for detecting errors where programs incor-
rectly rely on allocated memory being initialized to zero, or
reuse values in memory that has already been freed.
The default value for this parameter is 0.
M_TOP_PAD
This parameter defines the amount of padding to employ when call-
ing sbrk(2) to modify the program break. (The measurement unit
for this parameter is bytes.) This parameter has an effect in
the following circumstances:
• When the program break is increased, then M_TOP_PAD bytes are
added to the sbrk(2) request.
• When the heap is trimmed as a consequence of calling free(3)
(see the discussion of M_TRIM_THRESHOLD) this much free space
is preserved at the top of the heap.
In either case, the amount of padding is always rounded to a sys-
tem page boundary.
Modifying M_TOP_PAD is a trade-off between increasing the number
of system calls (when the parameter is set low) and wasting un-
used memory at the top of the heap (when the parameter is set
high).
The default value for this parameter is 128*1024.
M_TRIM_THRESHOLD
When the amount of contiguous free memory at the top of the heap
grows sufficiently large, free(3) employs sbrk(2) to release this
memory back to the system. (This can be useful in programs that
continue to execute for a long period after freeing a significant
amount of memory.) The M_TRIM_THRESHOLD parameter specifies the
minimum size (in bytes) that this block of memory must reach be-
fore sbrk(2) is used to trim the heap.
The default value for this parameter is 128*1024. Setting
M_TRIM_THRESHOLD to -1 disables trimming completely.
Modifying M_TRIM_THRESHOLD is a trade-off between increasing the
number of system calls (when the parameter is set low) and wast-
ing unused memory at the top of the heap (when the parameter is
set high).
Environment variables
A number of environment variables can be defined to modify some of the
same parameters as are controlled by mallopt(). Using these variables
has the advantage that the source code of the program need not be
changed. To be effective, these variables must be defined before the
first call to a memory-allocation function. (If the same parameters are
adjusted via mallopt(), then the mallopt() settings take precedence.)
For security reasons, these variables are ignored in set-user-ID and
set-group-ID programs.
The environment variables are as follows (note the trailing underscore
at the end of the name of some variables):
MALLOC_ARENA_MAX
Controls the same parameter as mallopt() M_ARENA_MAX.
MALLOC_ARENA_TEST
Controls the same parameter as mallopt() M_ARENA_TEST.
MALLOC_CHECK_
This environment variable controls the same parameter as mal-
lopt() M_CHECK_ACTION. If this variable is set to a nonzero
value, then a special implementation of the memory-allocation
functions is used. (This is accomplished using the mal-
loc_hook(3) feature.) This implementation performs additional
error checking, but is slower than the standard set of memory-al-
location functions. (This implementation does not detect all
possible errors; memory leaks can still occur.)
The value assigned to this environment variable should be a sin-
gle digit, whose meaning is as described for M_CHECK_ACTION. Any
characters beyond the initial digit are ignored.
For security reasons, the effect of MALLOC_CHECK_ is disabled by
default for set-user-ID and set-group-ID programs. However, if
the file /etc/suid-debug exists (the content of the file is ir-
relevant), then MALLOC_CHECK_ also has an effect for set-user-ID
and set-group-ID programs.
MALLOC_MMAP_MAX_
Controls the same parameter as mallopt() M_MMAP_MAX.
MALLOC_MMAP_THRESHOLD_
Controls the same parameter as mallopt() M_MMAP_THRESHOLD.
MALLOC_PERTURB_
Controls the same parameter as mallopt() M_PERTURB.
MALLOC_TRIM_THRESHOLD_
Controls the same parameter as mallopt() M_TRIM_THRESHOLD.
MALLOC_TOP_PAD_
Controls the same parameter as mallopt() M_TOP_PAD.
RETURN VALUE
On success, mallopt() returns 1. On error, it returns 0.
ERRORS
On error, errno is not set.
VERSIONS
A similar function exists on many System V derivatives, but the range of
values for param varies across systems. The SVID defined options M_MX-
FAST, M_NLBLKS, M_GRAIN, and M_KEEP, but only the first of these is im-
plemented in glibc.
STANDARDS
None.
HISTORY
glibc 2.0.
BUGS
Specifying an invalid value for param does not generate an error.
A calculation error within the glibc implementation means that a call of
the form:
mallopt(M_MXFAST, n)
does not result in fastbins being employed for all allocations of size
up to n. To ensure desired results, n should be rounded up to the next
multiple greater than or equal to (2k+1)*sizeof(size_t), where k is an
integer.
If mallopt() is used to set M_PERTURB, then, as expected, the bytes of
allocated memory are initialized to the complement of the byte in value,
and when that memory is freed, the bytes of the region are initialized
to the byte specified in value. However, there is an off-by-
sizeof(size_t) error in the implementation: instead of initializing pre-
cisely the block of memory being freed by the call free(p), the block
starting at p+sizeof(size_t) is initialized.
EXAMPLES
The program below demonstrates the use of M_CHECK_ACTION. If the pro-
gram is supplied with an (integer) command-line argument, then that ar-
gument is used to set the M_CHECK_ACTION parameter. The program then
allocates a block of memory, and frees it twice (an error).
The following shell session shows what happens when we run this program
under glibc, with the default value for M_CHECK_ACTION:
$ ./a.out
main(): returned from first free() call
*** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 ***
======= Backtrace: =========
/lib/libc.so.6(+0x6c501)[0x523501]
/lib/libc.so.6(+0x6dd70)[0x524d70]
/lib/libc.so.6(cfree+0x6d)[0x527e5d]
./a.out[0x80485db]
/lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7]
./a.out[0x8048471]
======= Memory map: ========
001e4000-001fe000 r-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1
001fe000-001ff000 r--p 00019000 08:06 1083555 /lib/libgcc_s.so.1
[some lines omitted]
b7814000-b7817000 rw-p 00000000 00:00 0
bff53000-bff74000 rw-p 00000000 00:00 0 [stack]
Aborted (core dumped)
The following runs show the results when employing other values for
M_CHECK_ACTION:
$ ./a.out 1 # Diagnose error and continue
main(): returned from first free() call
*** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 ***
main(): returned from second free() call
$ ./a.out 2 # Abort without error message
main(): returned from first free() call
Aborted (core dumped)
$ ./a.out 0 # Ignore error and continue
main(): returned from first free() call
main(): returned from second free() call
The next run shows how to set the same parameter using the MALLOC_CHECK_
environment variable:
$ MALLOC_CHECK_=1 ./a.out
main(): returned from first free() call
*** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 ***
main(): returned from second free() call
Program source
#include <malloc.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
char *p;
if (argc > 1) {
if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) {
fprintf(stderr, "mallopt() failed");
exit(EXIT_FAILURE);
}
}
p = malloc(1000);
if (p == NULL) {
fprintf(stderr, "malloc() failed");
exit(EXIT_FAILURE);
}
free(p);
printf("%s(): returned from first free() call\n", __func__);
free(p);
printf("%s(): returned from second free() call\n", __func__);
exit(EXIT_SUCCESS);
}
SEE ALSO
mmap(2), sbrk(2), mallinfo(3), malloc(3), malloc_hook(3),
malloc_info(3), malloc_stats(3), malloc_trim(3), mcheck(3), mtrace(3),
posix_memalign(3)
Linux man-pages 6.9.1 2024-06-15 mallopt(3)
Generated by dwww version 1.16 on Tue Dec 16 04:25:43 CET 2025.