MALLOC(3X)MALLOC(3X)NAME
malloc, free, realloc, calloc, mallopt, mallinfo, mallocblksize,
recalloc, memalign - fast main memory allocator
SYNOPSIS
#include <sys/types.h>
#include <malloc.h>
void *malloc (size_t size);
void free (void *ptr);
void *realloc (void *ptr, size_t size);
void *calloc (size_t nelem, size_t elsize);
int mallopt (int cmd, int value);
struct mallinfo mallinfo(void);
size_t mallocblksize (void *ptr);
void *recalloc (void *ptr, size_t nelem, size_t elsize);
void *memalign (size_t align, size_t size);
DESCRIPTION
malloc and free provide a simple general-purpose memory allocation
package, which is more flexible than the malloc(3c) package and,
depending on an application's usage, may provide better performance. It
is found in the library ``libmalloc.so'', and is loaded if the option
``-lmalloc'' is used with cc(1) or ld(1).
malloc returns a pointer to a block of at least size bytes suitably
aligned for any use.
The argument to free is a pointer to a block previously allocated by
malloc; after free is performed this space is made available for further
allocation, and its contents are destroyed (see mallopt below for a way
to change this behavior).
Undefined results will occur if the space assigned by malloc is overrun
or if some random number is handed to free. It is always permitted to
pass NULL to free.
realloc changes the size of the block pointed to by ptr to size bytes and
returns a pointer to the (possibly moved) block. The contents will be
unchanged up to the lesser of the new and old sizes. In the special case
of a null ptr, realloc degenerates to malloc. A zero size causes the
passed block to be freed.
Page 1
MALLOC(3X)MALLOC(3X)calloc allocates space for an array of nelem elements of size elsize.
The space is initialized to zeros.
recalloc combines realloc and calloc. If the size of the block
increases, any new bytes are initialized to zero. Note that for this to
work properly, all allocations of a given pointer must go through
recalloc. If the original pointer was allocated with either malloc,
calloc, or realloc some new bytes may not be set properly to zero.
memalign allocates size bytes on a specified alignment boundary, and
returns a pointer to the allocated block. The value of the returned
address is guaranteed to be an even multiple of align. Note: the value
of align must be a multiple of a word (for 64 bit objects, a doubleword,)
and must be greater than or equal to the size of a word, or, for 64 bit
objects, the size of a doubleword.
mallocblksize returns the actual size of the block pointed to by ptr.
The returned size may be greater than the original requested size due to
padding and alignment.
mallopt provides for control over the allocation algorithm. The
available values for cmd are:
M_MXFAST Set maxfast to value. The algorithm allocates all blocks at or
below the size of maxfast in large groups and then doles them
out very quickly. The default value for maxfast is 28.
M_NLBLKS Set numlblks to value. The above mentioned ``large groups''
each contain numlblks blocks. numlblks must be greater than 0.
The default value for numlblks is 100.
M_GRAIN Set grain to value. Requests less than or equal to maxfast will
have the size of a pointer added to them and be rounded up to
the next multiple of grain. value will be rounded up to a
multiple of the alignment size (8 bytes for 32 bit programs, 16
bytes for 64 bit programs) when grain is set. grain must be
greater than 0. The default value of grain is 8 for 32 bit
programs, 16 for 64 bit programs.
M_KEEP Preserve data in a freed block until the next malloc, realloc,
or calloc. This option is provided only for compatibility with
older versions of malloc and is not recommended.
M_DEBUG Turns debug checking on if value is not equal to 0, otherwise
turns debug checking off. When debugging is on, each call to
malloc and free causes the entire malloc arena to be scanned and
checked for consistency. This option may be invoked at any
time. Note that when debug checking is on, the performance of
malloc is reduced considerably. If corruption is detected in
the arena, the checking code calls abort(3C). This usually
results in the calling process exiting and leaving a core file
in its current directory.
Page 2
MALLOC(3X)MALLOC(3X)
M_BLKSZ When malloc requires additional space, it uses sbrk(2) to
allocate enough memory for the current malloc request rounded up
to a minimum size (default is 8K). The new size is set to value
after it has been rounded up to the current block alignment.
value must be at least 512 bytes. If a lot of space is to be
allocated, setting the size larger can cut down on the system
overhead. This option may be invoked at any time.
M_MXCHK By default, malloc trades off time versus space - if anywhere in
the arena there is a block of the appropriate size, malloc will
find and return it. If the arena has become fragmented due to
many mallocs and frees, it is possible that malloc will have to
search through many blocks to find one of the appropriate size.
If the arena is severely fragmented, the average malloc time can
be on the order of tens of milliseconds (as opposed to a normal
average of tens of microseconds). This option allows the user
to place a limit on the number of blocks that malloc will search
through before allocating a new block of space from the system.
Small values (less than 50) can cause much more memory to be
allocated. Values around 100 (the default) cause very uniform
response time, with a small space penalty. This option may be
invoked at any time.
M_FREEHD When value is not zero, free, recalloc, and realloc will place
any freed memory in the front of the free list(s) instead of at
the end (which is the default). Some applications will benefit
in processing speed and space compaction by having freed memory
placed at the beginning of the free list(s).
M_CLRONFREE
With this option, all blocks that are freed are set to value.
This option may be set at any time, but there is no way to turn
it off. That part of the beginning of a freed block which is
used for internal pointers will of course not be set to value.
These values are defined in the <malloc.h> header file.
mallopt may be called repeatedly, but, for most commands, may not be
called after the first small block is allocated.
mallinfo provides instrumentation describing space usage. It returns the
structure (defined in <malloc.h>):
struct mallinfo {
int arena; /* total space in arena */
int ordblks; /* number of ordinary blocks */
int smblks; /* number of small blocks */
int hblkhd; /* space in holding block headers */
int hblks; /* number of holding blocks */
int usmblks; /* space in small blocks in use */
int fsmblks; /* space in free small blocks */
int uordblks; /* space in ordinary blocks in use */
Page 3
MALLOC(3X)MALLOC(3X)
int fordblks; /* space in free ordinary blocks */
int keepcost; /* space penalty if keep option */
/* is used */
}
For example, an application wishing to determine how many bytes it has
currently malloc'd should add the usmblks and uordblks fields. That
total may also include some space that malloc allocates internally for
its own use, and that extra space cannot be free'd.
Each of the allocation routines returns a pointer to space suitably
aligned (after possible pointer coercion) for storage of any type of
object.
SEE ALSObrk(2), malloc(3C), memalign(3C), amalloc(3P), valloc(3C).
DIAGNOSTICS
malloc, recalloc, memalign, realloc and calloc return a NULL pointer if
there is not enough available memory or size is 0. memalign will also
return NULL if align is 0 or not a 4 byte multiple (8 byte multiple for
64-bit programs). When realloc or recalloc returns NULL, the block
pointed to by ptr is left intact. If mallopt is called after any
allocation (for most cmd arguments) or if cmd or value are invalid, non-
zero is returned. Otherwise, it returns zero.
WARNINGS
Note that unlike malloc(3C), this package does not preserve the contents
of a block when it is freed, unless the M_KEEP option of mallopt is used.
Undocumented features of malloc(3C) have not been duplicated.
Products, libraries, or commands that provide their own malloc package
must provide all of the entry points listed above, or the normal
libmalloc or libc malloc entry point for the unimplmented routine(s) may
be called instead, leading to corrupted heaps, as it is unlikely that the
internal details of the heap management will be the same. If the package
is a replacement for the libc set, but not the libmalloc set, it is not
necessary to supply the mallopt, mallinfo, mallocblksize, or recalloc
routines.
Page 4
