Provided by: manpages-dev_3.35-0.1ubuntu1_all bug

NAME

       mallopt,       malloc_trim,      malloc_usable_size,      malloc_stats,
       malloc_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
       memory 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
              disables trimming.  Default: 128*1024.

       M_TOP_PAD
              When  sbrk()  is  called  with  a  positive argument to allocate
              additional  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
              allocated 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()
              implementation  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
              corruption 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
              asterisks ("*") 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
              excluding mmap, and later including mmap().

       malloc_get_state() returns a ...  malloc_set_state()

       mallinfo()  returns  a  struct  mallinfo  with  allocation information,
       similar to what is printed by malloc_stats().  The return  value  is  a
       structure,  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
                     allocation  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
                     routines 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
       implementation.

       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
       implementation by Doug Lea <dl@cs.oswego.edu>.

SEE ALSO

       sbrk(2),  mmap(2),  stderr(2),  malloc_hook(3),  malloc(3),   cfree(3),
       memalign(3), pvalloc(3).