GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


man:mallopt

MALLOPT(3) Linux Programmer's Manual MALLOPT(3)

NAME

     mallopt - set memory allocation parameters

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 num-
            ber 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 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 mes-
                   sage 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  mes-
                   sage  specified  by  bit  0, the program is terminated by
                   calling abort(3).  In glibc versions since 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 func-
                   tion  where the error was detected and the brief descrip-
                   tion 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 unde-
                    fined 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 map-
                    pings, and abort the program.
            Since glibc 2.3.4, the  default  value  for  the  M_CHECK_ACTION
            parameter is 3.  In glibc version 2.3.3 and earlier, the default
            value is 1.
            Using a nonzero M_CHECK_ACTION value can be useful because  oth-
            erwise  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  sig-
            nificance  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):  deal-
            located  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 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
            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 parame-
            ter 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  pro-
            grams  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 sig-
            nificant 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 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 prece-
     dence.)  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-
            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 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
            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.

CONFORMING TO

     This  function is not specified by POSIX or the C standards.  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  imple-
     mented in glibc.

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 ini-
     tialized 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.

EXAMPLE

     The  program below demonstrates the use of M_CHECK_ACTION.  If the pro-
     gram 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 MAL-
     LOC_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("main(): returned from first free() call\n");
         free(p);
         printf("main(): returned from second free() call\n");
         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)

COLOPHON

     This page is part of release 4.16 of the Linux man-pages project.  A
     description of the project, information about reporting bugs, and the
     latest version of this page, can be found at
     https://www.kernel.org/doc/man-pages/.

Linux 2017-09-15 MALLOPT(3)

/data/webs/external/dokuwiki/data/pages/man/mallopt.txt · Last modified: 2019/05/17 09:47 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki