.TH MALLOC 3  BRL/CAD
.SH NAME
malloc, free, realloc \- memory allocator
.SH SYNOPSIS
.nf
.B char *malloc(size)
.B Size size;
.PP
.B void free(ptr)
.B char *ptr;
.PP
.B char *realloc(ptr, size)
.B char *ptr;
.B Size size;
.PP
.B extern char endfree
.PP
.B extern void (*mlabort)()
.fi
.PP
Where
.I Size
is an integer large enough to hold a char pointer.
.SH DESCRIPTION
.I Malloc
and
.I free
provide a simple general-purpose memory allocation package.
.I Malloc
returns a pointer to a block of at least
.I size
bytes beginning on the boundary of the most stringent alignment required
by the architecture.
.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,
but its contents are left undisturbed.
.PP
Needless to say, grave disorder will result if the space assigned by
.I malloc
is overrun or if some random number is handed to
.IR free .
.PP
.I Malloc
maintains multiple lists of free blocks according to size,
allocating space from the appropriate list.
It calls
.I brk
(see
.IR brk (2))
to get more memory from the system when there is no
suitable space already free.
.PP
.I Free
makes an attempt to merge newly freed memory with adjacent free areas.
If the result of this merging is an area that touches the system break
(the current location of the highest valid address of the data segment of the
process) and if
.I
endfree
has a non-zero value,  then break is moved back, contracting the process
size and releasing the memory back to the system.
.PP
By default
.I endfree
has a value of 0, which disables the release of memory back to the system.
.PP
It is valid to also allocate memory by the use of
.I sbrk(3)
or by moving up the break with
.I brk(3).
This memory may be reclaimed and returned to
the \fImalloc\fP/\fIfree\fP arena by the use of
.I forget
(see \fIforget\fP(3)).
.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
In order to be compatible with older versions,
if
.I endfree
is 0, then
.I realloc
also works if
.I ptr
points to a block freed since the last call of
.I malloc
or
.I realloc.
Sequences of
.I free, malloc
and
.I realloc
were previously used to attempt storage compaction.
This procedure is no longer recommended.
In this implementation
.I Realloc,
.I malloc
and
.I free
do a fair amount of their own storage compaction anyway.
.SH DIAGNOSTICS
.I Malloc, realloc
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.
.I Realloc
makes an attempt to detect and return a null pointer when the break has been
moved so that the requested address is no longer valid.
.I Malloc
may be recompiled to check the arena very stringently on every transaction;
those sites with a source code license may do this by recompiling the source
with  -Ddebug .
.PP
On detection of corruption of the malloc arena the normal response is an
abort with a core dump.  This response can be changed by placing a pointer to
a function with the desired response into the extern pointer
.I mlabort.
.SH ALGORITHM
.I Malloc
returns a block of size equal to the size requested plus an overhead (24
bytes for a 32 bit machine).
Freed memory is linked into a chain selected by the size of the freed area
(currently, memory size of items in a chain is between two adjacent powers of
2).
The search for memory starts with the chain whose length index is at least
equal to the size of the request and proceeds if unsuccessful to larger
memory size chains.  If there is any surplus memory left after the filling
of a request it is returned to the appropriate free list chain.
.SH BUGS
When
.I realloc
returns 0, the block pointed to by
.I ptr
may have been destroyed.