term% cat index.txt MALLOC(2) System Calls Manual MALLOC(2)
NAME
malloc, mallocalign, mallocz, free, realloc, calloc, msize, setmalloc‐
tag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock -
memory allocator
SYNOPSIS
#include <u.h>
#include <libc.h>
void* malloc(ulong size)
void* mallocalign(ulong size, ulong align, long offset, ulong span)
void* mallocz(ulong size, int clr)
void free(void *ptr)
void* realloc(void *ptr, ulong size)
void* calloc(ulong nelem, ulong elsize)
ulong msize(void *ptr)
void setmalloctag(void *ptr, uintptr tag)
uintptrgetmalloctag(void *ptr)
void setrealloctag(void *ptr, uintptr tag)
uintptrgetrealloctag(void *ptr)
void* malloctopoolblock(void*)
DESCRIPTION
Malloc and free provide a simple memory allocation package. Malloc re‐
turns 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) re‐
turns 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 le‐
gal 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, ex‐
cept 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 returns a pointer to the newly-allocated memory
realloc(ptr, 0)
means 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 allo‐
cator 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
/sys/src/libc/port/malloc.c
SEE ALSO
leak(1), trump (in acid(1)), brk(2), getcallerpc(2), pool(2)
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 real‐
locate 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 exe‐
cution; 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.
MALLOC(2)