V8/usr/man/man3/malloc.3

.TH MALLOC 3 
.SH NAME
malloc, free, realloc, ialloc, calloc, cfree \- main memory allocator
.SH SYNOPSIS
.nf
.B char *malloc(size)
.B unsigned size;
.PP
.B free(ptr)
.B char *ptr;
.PP
.B char *realloc(ptr, size)
.B char *ptr;
.B unsigned size;
.PP
.B ialloc(ptr, size)
.B char *ptr;
.B unsigned size;
.PP
.B char *calloc(nelem, elsize)
.B unsigned nelem, elsize;
.PP
.B cfree(ptr)
.B char *ptr;
.fi
.SH DESCRIPTION
.I Malloc
and
.I free
provide a simple general-purpose memory allocation package.
.I Malloc
returns a pointer to a new block of at least
.I size
bytes.
.PP
The argument to
.I free
is a pointer to a block previously allocated by
.IR malloc ;
this space is made available for further allocation.
The present implementation of
.I free 
does not change the contents;
but it is unwise to depend on this fact.
.PP
.I Realloc
changes the size of the block pointed to by
.I ptr
to
.I 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.
.PP
.I Ialloc
inserts into the arena
a designated block of store that was not previously known to the
allocator.
.PP
.I Calloc
allocates space for
an array of
.I nelem
elements of size
.I elsize.
The space is initialized to zeros.
.I Cfree
frees such a block.
.PP
Each of the allocation routines returns a pointer
to space suitably aligned (after possible pointer coercion)
for storage of any type of object.
.PP
The arena, though not necessarily contiguous, is kept in strict
address order.
.I Malloc
allocates the first big enough contiguous reach of
free space
found in a circular search from the last 
block allocated or freed,
coalescing adjacent free blocks as it searches.
It calls
.I sbrk
(see
.IR break (2))
to get more memory from the system when there is no
suitable space already free.
It has been arranged that 
.I realloc
will work on a block that has been freed, provided no
other allocations have intervened.
This questionable, unportable practice allows
combinations of
.I free,
.I realloc
and
.I malloc
to be used to rearrange the arena.
.SH SEE ALSO
galloc(3), sbrk(2)
.SH DIAGNOSTICS
.I Malloc, realloc
and
.I calloc
return a null pointer (0) if there is no available memory
or if the arena has been detectably corrupted by storing outside the bounds
of a block.
A very stringently checking version of
.IR malloc ,
which aborts with a diagnostic if the arena is corrupted,
can be created by recompilation with a debugging flag set;
see the source.
.SH BUGS
When
.I realloc
returns 0,
the block
pointed to by
.I ptr
may be destroyed.
.br
.I Malloc
is general, not fast.
A program that repeatedly allocates and frees a particular kind of block 
often can be speeded up by superimposing a block-cacheing
or suballocation scheme on top of 
.I malloc-free.