mallopt man page on Debian

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

MALLOPT(3)							    MALLOPT(3)

NAME
       mallopt,	   malloc_trim,	   malloc_usable_size,	  malloc_stats,	  mal‐
       loc_get_state, malloc_set_state, mallinfo - dynamic allocation tuning

SYNOPSIS
       #include <malloc.h>

       int mallopt (int param, int value);
       int malloc_trim (size_t pad);
       size_t malloc_usable_size (void *ptr);
       void malloc_stats (void);
       void *malloc_get_state (void);
       int malloc_set_state (void *ptr);
       struct mallinfo mallinfo (void);

DESCRIPTION
       These functions allow glibc-specific interaction with the dynamic  mem‐
       ory allocation routines.

       mallopt()  allows tuning of the parameters affecting allocation.	 param
       is one of the constants listed below;  value  should  be	 specified  in
       bytes.

       M_MXFAST
	      Free  chunks  not	 larger than the given value are not joined to
	      adjacent free chunks; larger ones are joined.  This is  intended
	      to optimize future requests for small chunks of the same size as
	      previously freed	chunks.	  Allowed  values  are	in  the	 range
	      [0-80];  a  value	 of  0	causes	all  free chunks to be joined.
	      Default: 64.

       M_TRIM_THRESHOLD
	      Unused memory is returned to the OS when the size	 available  to
	      be returned exceeds the given value.

	      Note  that  not  all unused memory is able to be returned to the
	      OS; in particular, it is not possible to return an unused	 block
	      when  an	in-use block lies between it and the “top” of the data
	      segment.	However, the free block may be used to satisfy	future
	      allocation requests.

	      Smaller values for this parameter cause sbrk() to be called more
	      frequently with a negative argument, reducing memory usage,  but
	      with  increased  overhead of extra syscalls.  A value of -1 dis‐
	      ables trimming.  Default: 128*1024.

       M_TOP_PAD
	      When sbrk() is called with a positive argument to allocate addi‐
	      tional  address  space,  the given value specifies an additional
	      amount to be allocated, beyond what is necessary to satisfy  the
	      request.	 This  value  also  defines an amount of address space
	      which is not released to the OS when sbrk()  is  called  with  a
	      negative	argument.  Again, the intent is to minimize the number
	      of syscalls, without needlessly using  large  usage  of  memory.
	      Default: 0 (allocation requests are internally rounded up to the
	      page size, and the extra allocated size is already sufficient to
	      reduce the syscall overhead).

       M_MMAP_THRESHOLD
	      When an allocation request larger than the given value cannot be
	      satisfied by an existing free chunk, the memory is guaranteed to
	      be  obtained  with  mmap().  Smaller requests might be allocated
	      with either of mmap() or sbrk().	mmap()-allocated memory can be
	      immediately returned to the OS when it is freed, but this is not
	      true for all memory allocated with sbrk(); however, memory allo‐
	      cated by mmap() and later freed is neither joined nor reused, so
	      the overhead is greater.	Default: 128*1024.

       M_MMAP_MAX
	      The given value sets  the	 maximum  number  of  mmap()-allocated
	      chunks allowed to be in use at a given time (even if the size of
	      the allocation request exceeds the value of the M_MMAP_THRESHOLD
	      parameter).   This  is useful on systems where the mmap() imple‐
	      mentation scales poorly.	A value	 of  0	disables  the  use  of
	      mmap().  Default: 65536.

       M_CHECK_ACTION
	      The 3 low bits of this value control the behavior when heap cor‐
	      ruption is detected.

	      If set to 0, errors are silently ignored (but  the  behavior  of
	      the program is undefined).

	      If  the  low  bit	 is  set,  an error message is printed; If the
	      third-lowest bit is unset, the message is surrounded  by	aster‐
	      isks ("*") and includes the relevant pointer address.

	      If  the second-lowest bit is set, the program is then terminated
	      with abort().

	      The default value for glibc 2.3.3 and  earlier  was  1,  causing
	      only  an	informative message to be output.  glibc-2.3.4 changes
	      the default to 3, which also causes the program to abort.

       malloc_trim() explicitly requests  that	any  unused  memory  space  be
       returned	 to  the OS.  Note that this happens automatically when free()
       is called with a sufficiently large chunk; see the M_TRIM_THRESHOLD and
       M_TOP_PAD  parameters,  above.  pad specifies the number of bytes to be
       retained for use in future allocation requests; when called by  free(),
       this is the value of M_TOP_PAD.

       malloc_usable_size()  returns  the  number  of  bytes  available in the
       dynamically allocated  buffer  ptr,  which  may	be  greater  than  the
       requested  size	(but  is  guaranteed  to  be at least as large, if the
       request was successful).	 Typically, you	 should	 store	the  requested
       allocation size rather than use this function.

       malloc_stats()  outputs	to stderr some information about the program's
       usage of dynamic memory.	 Information for each arena is displayed.

	      system bytes is the amount of address space obtained from the OS

	      in use bytes is the amount of that space which the  program  has
	      requested and are in use.

	      max  mmap	 regions is largest number of mmap() regions allocated
	      at a given time.

	      max mmap bytes is the largest total amount of address space ever
	      allocated by mmap() at a given time.

	      system bytes and in use bytes output appears twice, once exclud‐
	      ing mmap, and later including mmap().

       malloc_get_state() returns a ...	 malloc_set_state()

       mallinfo() returns a struct mallinfo with allocation information, simi‐
       lar to what is printed by malloc_stats().  The return value is a struc‐
       ture, not a pointer; it is thread-safe.	Only the information  for  the
       main arena is returned.	The structure contains the following members:

	      int arena;
		     Address  space  used  by the dynamic allocation routines,
		     not including that from mmap()

	      int ordblks;
		     Count of independent, unused chunks

	      int smblks;
		     Count of chunks small enough to qualify for fast  alloca‐
		     tion  without  being joined to adjacent free chunks; this
		     field is not meaningful in the glibc implementation.

	      int hblks;
		     Count of chunks allocated by mmap()

	      int hblkhd;
		     Address space allocated by the  dynamic  allocation  rou‐
		     tines using mmap()

	      int usmblks;
		     Largest amount of address space ever used by the process;
		     this field is not meaningful in the glibc implementation.

	      int fsmblks;
		     Total unused address space in small,  non-joined  chunks;
		     this field is not meaningful in the glibc implementation.

	      int uordblks;
		     Dynamically  allocated address space used by the program,
		     including	book-keeping  overhead	 per   allocation   of
		     sizeof(void *) bytes.

	      int fordblks;
		     Unused address space, including that from mmap()

	      int keepcost;
		     Upper  bound on the address space available for return to
		     the OS by malloc_trim().

RETURN VALUE
       mallopt() returns 1 on success, and 0 on failure.

       malloc_trim() returns 1 if any memory was returned to  the  OS,	and  0
       otherwise.

       malloc_usable_size()  returns  the  usable size of the allocated region
       beginning at ptr, or 0 if ptr is NULL.

       malloc_get_state() returns a pointer to a description of the  state  of
       the allocation routines, or NULL on error.

       malloc_set_state() returns 0 on success, and nonzero on error.

       mallinfo() returns a structure containing information about the dynamic
       memory use of the program.

NOTES
       The glibc malloc implementation is modified to allow  use  of  multiple
       "arenas";  the  malloc_stats() output is not as described in the header
       files and documentation,	 and  the  mallinfo()  function	 only  returns
       information for the main arena.

       The default values listed for the mallopt() parameters may vary between
       installations, and should only serve as a guideline while tweaking  the
       values;	refer to the source code for your distribution's glibc package
       to establish the real defaults.

ENVIRONMENT
       Since libc 5.4.23, the mallopt() tuning parameters  are	accessible  at
       runtime through the following environment variables:

	      MALLOC_TRIM_THRESHOLD_
	      MALLOC_TOP_PAD_
	      MALLOC_MMAP_THRESHOLD_
	      MALLOC_MMAP_MAX_
	      MALLOC_CHECK_

       Only the first byte of MALLOC_CHECK_ is considered; "10" is interpreted
       as 1, and "64" is interpreted as 6.

CONFORMING TO
       mallopt() and mallinfo(), and M_MXFAST are defined by SVID/XPG.

       That standard also defines the mallopt() parameters M_NLBLKS,  M_GRAIN,
       and  M_KEEP,  but  these values have no effect in the glibc implementa‐
       tion.

       The remainder of these functions and variables are GNU extensions,  and
       should not be used in programs intended to be portable.

AUTHOR
       glibc uses a dynamic allocation routines heavily based on the implemen‐
       tation by Doug Lea <dl@cs.oswego.edu>.

SEE ALSO
       sbrk(2), mmap(2), stderr(2), malloc_hook(3), malloc(3), cfree(3), mema‐
       lign(3), pvalloc(3).

GNU				  21 May 2006			    MALLOPT(3)
[top]

List of man pages available for Debian

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