diff options
Diffstat (limited to 'man/man3/malloc.3')
| -rw-r--r-- | man/man3/malloc.3 | 207 |
1 files changed, 207 insertions, 0 deletions
diff --git a/man/man3/malloc.3 b/man/man3/malloc.3 new file mode 100644 index 00000000..c75ef29d --- /dev/null +++ b/man/man3/malloc.3 @@ -0,0 +1,207 @@ +.TH MALLOC 3 +.SH NAME +malloc, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock \- memory allocator +.SH SYNOPSIS +.B #include <u.h> +.br +.B #include <libc.h> +.PP +.ta \w'\fLvoid* 'u +.B +void* malloc(ulong size) +.PP +.B +void* mallocz(ulong size, int clr) +.PP +.B +void free(void *ptr) +.PP +.B +void* realloc(void *ptr, ulong size) +.PP +.B +void* calloc(ulong nelem, ulong elsize) +.PP +.B +ulong msize(void *ptr) +.PP +.B +void setmalloctag(void *ptr, ulong tag) +.PP +.B +ulong getmalloctag(void *ptr, ulong tag) +.PP +.B +void setrealloctag(void *ptr, ulong tag) +.PP +.B +ulong getrealloctag(void *ptr, ulong tag) +.PP +.B +void* malloctopoolblock(void*) +.PP +.SH DESCRIPTION +.I Malloc +and +.I free +provide a simple memory allocation package. +.I Malloc +returns a pointer to a new block of at least +.I size +bytes. +The block is suitably aligned for storage of any type of object. +No two active pointers from +.I malloc +will have the same value. +The call +.B malloc(0) +returns a valid pointer rather than null. +.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. +It is legal to free a null pointer; the effect is a no-op. +The contents of the space returned by +.I malloc +are undefined. +.I Mallocz +behaves as +.IR malloc , +except that if +.I clr +is non-zero, the memory returned will be zeroed. +.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. +.I Realloc +takes on special meanings when one or both arguments are zero: +.TP +.B "realloc(0,\ size) +means +.LR malloc(size) ; +returns a pointer to the newly-allocated memory +.TP +.B "realloc(ptr,\ 0) +means +.LR free(ptr) ; +returns null +.TP +.B "realloc(0,\ 0) +no-op; returns null +.PD +.PP +.I Calloc +allocates space for +an array of +.I nelem +elements of size +.IR elsize . +The space is initialized to zeros. +.I Free +frees such a block. +.PP +When a block is allocated, sometimes there is some extra unused space at the end. +.I Msize +grows the block to encompass this unused space and returns the new number +of bytes that may be used. +.PP +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 +.IR setmalloctag , +.IR getmalloctag , +.IR setrealloctag , +and +.IR getrealloctag . +When allocating blocks directly with +.I malloc +and +.IR 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 +.IR getcallerpc (2) +to +.IR setmalloctag ) +to provide more useful information about +the source of allocation. +.PP +.I Malloctopoolblock +takes the address of a block returned by +.I malloc +and returns the address of the corresponding +block allocated by the +.IR pool (2) +routines. +.SH SOURCE +.B /sys/src/libc/port/malloc.c +.SH SEE ALSO +.IR leak (1), +.I trump +(in +.IR acid (1)), +.IR brk (2), +.IR getcallerpc (2), +.IR pool (2) +.SH DIAGNOSTICS +.I Malloc, realloc +and +.I calloc +return 0 if there is no available memory. +.I Errstr +is likely to be set. +If the allocated blocks have no malloc or realloc tags, +.I getmalloctag +and +.I getrealloctag +return +.BR ~0 . +.PP +After including +.BR pool.h , +the call +.B 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 with setting +.EX + mainmem->flags |= POOL_NOREUSE; +.EE +at the beginning of your program. +This will cause malloc not to reallocate blocks even +once they are freed; +.B poolcheck(mainmem) +will then detect writes to freed blocks. +.PP +The +.I trump +library for +.I acid +can be used to obtain traces of malloc execution; see +.IR acid (1). +.SH BUGS +The different specification of +.I calloc +is bizarre. +.PP +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 +.I malloc +and +.I free +detect such corruption, they abort. |