Section: C Library Functions (3)
Updated: 21 May 2006
Return to Main Contents
mallopt, malloc_trim, malloc_usable_size, malloc_stats, malloc_get_state, malloc_set_state, mallinfo - dynamic allocation tuning
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);
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.
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.
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
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.
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
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.
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.
The 3 low bits of this value control the behavior when heap corruption
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
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
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
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.
in use bytes
output appears twice, once excluding mmap, and later including
malloc_get_state() returns a ...
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
- 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
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.
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.
Since libc 5.4.23, the mallopt() tuning parameters are
accessible at runtime through the following environment variables:
Only the first byte of MALLOC_CHECK_ is considered; "10" is
interpreted as 1, and "64" is interpreted as 6.
mallopt() and mallinfo(), and M_MXFAST are defined
That standard also defines the mallopt() parameters
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.
glibc uses a dynamic allocation routines heavily based on the
implementation by Doug Lea <firstname.lastname@example.org>.
- RETURN VALUE
- CONFORMING TO
- SEE ALSO
This document was created by
using the manual pages.