mallopt(3) — Linux manual page

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | VERSIONS | STANDARDS | HISTORY | BUGS | EXAMPLES | SEE ALSO

mallopt(3)              Library Functions Manual              mallopt(3)

NAME         top

       mallopt - set memory allocation parameters

LIBRARY         top

       Standard C library (libc, -lc)

SYNOPSIS         top

       #include <malloc.h>

       int mallopt(int param, int value);

DESCRIPTION         top

       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         top

       On success, mallopt() returns 1.  On error, it returns 0.

ERRORS         top

       On error, errno is not set.

VERSIONS         top

       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         top

       None.

HISTORY         top

       glibc 2.0.

BUGS         top

       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         top

       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);
       }

SEE ALSO         top

       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 (unreleased)     (date)                       mallopt(3)

Pages that refer to this page: mallinfo(3)malloc(3)malloc_get_state(3)malloc_info(3)malloc_stats(3)malloc_trim(3)mcheck(3)