Ubuntu Manpage: mallopt - set memory allocation parameters

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 represents a pool of memory that
can be used by malloc(3) (and similar) 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 contention, 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
--enable-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 determine 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 available 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
--enable-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 behavior, 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 description 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
program also prints a stack trace in the manner of backtrace(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 undefined results).

1 Print a detailed error message and continue execution.

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 parameter 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 otherwise 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 requests 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 significance and which
serves only as a safeguard. Setting this parameter to 0 disables the use of
mmap(2) for servicing large allocation 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 released 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 allocations; 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
factors 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
DEFAULT_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 DEFAULT_MMAP_THRESHOLD_MAX are freed, the threshold is
adjusted upward to the size of the freed block. When dynamic mmap thresholding is
in effect, the threshold for trimming the heap is also dynamically adjusted to be
twice the dynamic mmap threshold. Dynamic adjustment of the mmap threshold is
disabled if any of the M_TRIM_THRESHOLD, M_TOP_PAD, M_MMAP_THRESHOLD, or M_MMAP_MAX
parameters is set.

M_MXFAST (since glibc 2.3)
Set the upper limit for memory allocation requests that are satisfied using
"fastbins". (The measurement unit for this parameter 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 program 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 allocated memory (other
than allocations via calloc(3)) are initialized 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 incorrectly 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 calling 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 system 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 unused 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 before 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 wasting 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 mallopt() 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
malloc_hook(3) feature.) This implementation performs additional error checking,
but is slower than the standard set of memory-allocation functions. (This
implementation does not detect all possible errors; memory leaks can still occur.)

The value assigned to this environment variable should be a single 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 irrelevant), 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_MXFAST, M_NLBLKS, M_GRAIN, and  M_KEEP,
       but only the first of these is implemented 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  precisely  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 program is supplied with
       an  (integer)  command-line argument, then that argument 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);
       }