mallopt man page on Gentoo

Man page or keyword search:  
man Server   6889 pages
apropos Keyword Search (all sections)
Output format
Gentoo logo
[printable version]

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

       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.

       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  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 3.63 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)
[top]

List of man pages available for Gentoo

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net