GNU.WIKI: The GNU/Linux Knowledge Base

  [HOME] [PHP Manual] [HowTo] [ABS] [MAN1] [MAN2] [MAN3] [MAN4] [MAN5] [MAN6] [MAN7] [MAN8] [MAN9]

  [0-9] [Aa] [Bb] [Cc] [Dd] [Ee] [Ff] [Gg] [Hh] [Ii] [Jj] [Kk] [Ll] [Mm] [Nn] [Oo] [Pp] [Qq] [Rr] [Ss] [Tt] [Uu] [Vv] [Ww] [Xx] [Yy] [Zz]


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_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).  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
                     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 version 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  servers  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.

       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 each variable):

       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.

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

       The  MALLOC_MMAP_THRESHOLD_  and  MALLOC_MMAP_MAX_  variables  are  not
       ignored in set-group-ID programs.

       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.

EXAMPLE

       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("main(): returned from first free() call
");

           free(p);
           printf("main(): returned from second free() call
");

           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 3.65 of the Linux man-pages project.  A
       description of the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.



  All copyrights belong to their respective owners. Other content (c) 2014-2018, GNU.WIKI. Please report site errors to webmaster@gnu.wiki.
Page load time: 0.110 seconds. Last modified: November 04 2018 12:49:43.