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