Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

Linux 2.6 - man page for mallopt (linux section 3)

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-alloca-
       tion functions (see malloc(3)).	The param argument specifies the parameter  to	be  modi-
       fied, 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 program-
	      ming errors are detected (e.g., freeing the same pointer twice).	The 3 least  sig-
	      nificant	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-alloca-
		     tion  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 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 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  con-
	      trast,  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 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  DEFAULT_MMAP_THRESH-
	      OLD_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 dynamically adjusted to be
	      twice the dynamic mmap threshold.  Dynamic adjustment of the mmap threshold is dis-
	      abled  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  "fast-
	      bins".   (The  measurement unit for this parameter is bytes.)  Fastbins are storage
	      areas that hold deallocated blocks of memory of the same size without merging adja-
	      cent  free  blocks.  Subsequent reallocation of blocks of the same size can be han-
	      dled 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 dis-
	      ables 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 mod-
	      ify 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 min-
	      imum 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 rea-
       sons, 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  mal-
	      loc_hook(3) feature.)  This implementation performs additional error checking,  but
	      is  slower than the standard set of memory-allocation functions.	(This implementa-
	      tion 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 vari-
       able:

	   $ 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.55 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)


All times are GMT -4. The time now is 04:52 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password