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_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 sim-
		     plified 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 prob-
	      lem 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  parame-
	      ter  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  parame-
	      ter 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  upwards
	      to  the  size  of the freed block.  When dynamic mmap thresholding is in effect, the threshold for trimming the heap is also dynami-
	      cally 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 frag-
	      mentation 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  vari-
       ables  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 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 imple-
	      mentation 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 val-
       ues 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.44 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/.

Linux								    2012-04-30								MALLOPT(3)