# mallopt

## 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.
    


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


* * *