search..
No manual entry for -- in section 3
mallopt(3)		    Library Functions Manual		     mallopt(3)

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  rep-
	      resents a pool of memory that can be used by malloc(3) (and simi-
	      lar)  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  con-
	      tention, 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  --en-
	      able-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	 deter-
	      mine  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	 avail-
	      able  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 --en-
	      able-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 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 descrip-
		     tion 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 pro-
		     gram also prints a stack trace  in	 the  manner  of  back-
		     trace(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 un-
			  defined results).

		   1	  Print	 a  detailed  error message and continue execu-
			  tion.

		   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 para-
	      meter 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 other-
	      wise  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  re-
	      quests  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 signif-
	      icance and which serves only as a safeguard.  Setting this  para-
	      meter  to 0 disables the use of mmap(2) for servicing large allo-
	      cation 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  re-
	      leased 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 alloca-
	      tions; 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  fac-
	      tors   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  DE-
	      FAULT_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  DE-
	      FAULT_MMAP_THRESHOLD_MAX are freed, the threshold is adjusted up-
	      ward  to	the size of the freed block.  When dynamic mmap thresh-
	      olding is in effect, the threshold for trimming the heap is  also
	      dynamically adjusted to be twice the dynamic mmap threshold.  Dy-
	      namic  adjustment of the mmap threshold is disabled if any of the
	      M_TRIM_THRESHOLD, M_TOP_PAD, M_MMAP_THRESHOLD, or M_MMAP_MAX  pa-
	      rameters 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 pro-
	      gram 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 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 programs incor-
	      rectly 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 call-
	      ing  sbrk(2)  to modify the program break.  (The measurement unit
	      for this parameter is bytes.)  This parameter has	 an  effect  in
	      the following circumstances:

	      o	 When  the program break is increased, then M_TOP_PAD bytes are
		 added to the sbrk(2) request.

	      o	 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 sys-
	      tem 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 un-
	      used 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  be-
	      fore 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 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  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-al-
	      location	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 ir-
	      relevant), 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_MX-
       FAST, M_NLBLKS, M_GRAIN, and M_KEEP, but only the first of these is  im-
       plemented in glibc.

STANDARDS
       None.

HISTORY
       glibc 2.0.

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 pre-
       cisely  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  pro-
       gram  is supplied with an (integer) command-line argument, then that ar-
       gument 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
       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 6.9.1		   2024-06-15			     mallopt(3)