MALLOC(3) MALLOC(3)
NAME
malloc, mallocz, free, realloc, calloc, setmalloctag,
setrealloctag, getmalloctag, getrealloctag - memory
allocator
SYNOPSIS
#include <u.h>
#include <libc.h>
void* malloc(ulong size)
void* mallocz(ulong size, int clr)
void free(void *ptr)
void* realloc(void *ptr, ulong size)
void* calloc(ulong nelem, ulong elsize)
void setmalloctag(void *ptr, ulong tag)
ulong getmalloctag(void *ptr)
void setrealloctag(void *ptr, ulong tag)
ulong getrealloctag(void *ptr)
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 fur-
ther 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.
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-
Page 1 Plan 9 (printed 11/18/24)
MALLOC(3) MALLOC(3)
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.
The memory allocator on Plan 9 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(3)
to setmalloctag) to provide more useful information about
the source of allocation.
SOURCE
/usr/local/plan9/src/lib9/malloc.c
/usr/local/plan9/src/lib9/malloctag.c
SEE ALSO
trump (in acid(1)), getcallerpc(3)
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.
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.
To avoid name conflicts with the system versions of these
functions, malloc, realloc, calloc, and free are
Page 2 Plan 9 (printed 11/18/24)
MALLOC(3) MALLOC(3)
preprocessor macros defined as p9malloc, p9realloc,
p9calloc, and p9free; see intro(3).
Page 3 Plan 9 (printed 11/18/24)