DESCRIPTION

Malloc
and
free
provide a simple memory allocation package.
Malloc
returns a pointer to a new block of at least
size
bytes.
The block is suitably aligned for storage of any type of object.
No two active pointers from
malloc
will have the same value.
The call
malloc(0)
returns a valid pointer rather than null.

The argument to
free
is a pointer to a block previously allocated by
malloc;
this space is made available for further allocation.
It is legal to free a null pointer; the effect is a no-op.
The contents of the space returned by
malloc
are undefined.
Mallocz
behaves as
malloc,
except that if
clr
is non-zero, the memory returned will be zeroed.

Mallocalign
allocates a block of at least
n
bytes of memory respecting alignment contraints.
If
align
is non-zero,
the returned pointer is aligned to be equal to
offset
modulo
align.
If
span
is non-zero,
the
n
byte block allocated will not span a
span-byte
boundary.

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.
Realloc
takes on special meanings when one or both arguments are zero:

realloc(0, size)

means
malloc(size);
returns a pointer to the newly-allocated memory

realloc(ptr, 0)

means
free(ptr);
returns null

realloc(0, 0)

no-op; returns null

Calloc
allocates space for
an array of
nelem
elements of size
elsize.
The space is initialized to zeros.
Free
frees such a block.

When a block is allocated, sometimes there is some extra unused space at the end.
Msize
grows the block to encompass this unused space and returns the new number
of bytes that may be used.

The memory allocator maintains two word-sized fields
associated with each block, the “malloc tag” and the “realloc tag”.
By convention, the malloc tag is the PC that allocated the block,
and the realloc tag the PC that last reallocated the block.
These may be set or examined with
setmalloctag,getmalloctag,setrealloctag,
and
getrealloctag.
When allocating blocks directly with
malloc
and
realloc,
these tags will be set properly.
If a custom allocator wrapper is used,
the allocator wrapper can set the tags
itself (usually by passing the result of
getcallerpc(2)
to
setmalloctag)
to provide more useful information about
the source of allocation.

Malloctopoolblock
takes the address of a block returned by
malloc
and returns the address of the corresponding
block allocated by the
pool(2)
routines.

SOURCE

SEE

DIAGNOSTICS

Malloc, realloc
and
calloc
return 0 if there is no available memory.
Errstr
is likely to be set.
If the allocated blocks have no malloc or realloc tags,
getmalloctag
and
getrealloctag
return
~0.

After including
pool.h,
the call
poolcheck(mainmem)
can be used to scan the storage arena for inconsistencies
such as data written beyond the bounds of allocated blocks.
It is often useful to combine this with setting

mainmem->flags |= POOL_NOREUSE;

at the beginning of your program.
This will cause malloc not to reallocate blocks even
once they are freed;
poolcheck(mainmem)
will then detect writes to freed blocks.

The
trump
library for
acid
can be used to obtain traces of malloc execution; see
acid(1).

BUGS

The different specification of
calloc
is bizarre.

User errors can corrupt the storage arena.
The most common gaffes are (1) freeing an already freed block,
(2) storing beyond the bounds of an allocated block, and (3)
freeing data that was not obtained from the allocator.
When
malloc
and
free
detect such corruption, they abort.