.TH MALLOC 2.SH NAMEmalloc, 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.Bvoid*	malloc(ulong size).PP.Bvoid*	mallocz(ulong size, int clr).PP.Bvoid	free(void *ptr).PP.Bvoid*	realloc(void *ptr, ulong size).PP.Bvoid*	calloc(ulong nelem, ulong elsize).PP.Bulong	msize(void *ptr).PP.Bvoid	setmalloctag(void *ptr, ulong tag).PP.Bulong	getmalloctag(void *ptr, ulong tag).PP.Bvoid	setrealloctag(void *ptr, ulong tag).PP.Bulong	getrealloctag(void *ptr, ulong tag).PP.SH DESCRIPTION.I Mallocand.I freeprovide a simple memory allocation package..I Mallocreturns a pointer to a new block of at least.I sizebytes.The block is suitably aligned for storage of any type of object.No two active pointers from.I mallocwill have the same value.Incompatibly with ANSI C,the call.B malloc(0)returns a valid pointer rather than null..PPThe argument to.I freeis 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 mallocare undefined..I Malloczbehaves as .IR malloc ,except that if .I clris non-zero, the memory returned will be zeroed..PP.I Reallocchanges the size of the block pointed to by.I ptrto.I sizebytes and returns a pointer to the (possibly moved)block.The contents will be unchanged up to thelesser of the new and old sizes.The call.B "realloc(0,\ size)means the same as.LR malloc(size) .Further,the call.B "realloc(ptr,\ 0)means the same as.LR free(ptr) ..PP.I Callocallocates space foran array of.I nelemelements of size.IR elsize .The space is initialized to zeros..I Freefrees such a block..PPWhen a block is allocated, sometimes there is some extra unused space at the end..I Msizegrows the block to encompass this unused space and returns the new numberof bytes that may be used..PPThe memory allocator maintains two word-sized fieldsassociated 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 mallocand.IR realloc ,these tags will be set properly.If a custom allocator wrapper is used,the allocator wrapper can set the tagsitself (usually by passing the result of.IR getcallerpc (2) to .IR setmalloctag )to provide more useful information aboutthe source of allocation..PP.I Malloctopoolblocktakes the address of a block returned by.I mallocand returns the address of the correspondingblock 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, reallocand.I callocreturn 0 if there is no available memory..I Errstris likely to be set.If the allocated blocks have no malloc or realloc tags,.I getmalloctagand.I getrealloctagreturn.BR ~0 ..PPAfter including.BR pool.h ,the call.B poolcheck(mainmem)can be used to scan the storage arena for inconsistenciessuch as data written beyond the bounds of allocated blocks.It is often useful to combine this with with setting.EX    mainmem->flags |= POOL_NOREUSE;.EEat the beginning of your program.This will cause malloc not to reallocate blocks evenonce they are freed;.B poolcheck(mainmem)will then detect writes to freed blocks..PPThe .I trumplibrary for.I acidcan be used to obtain traces of malloc execution; see.IR acid (1)..SH BUGSThe different specification of.I callocis bizarre..PPUser 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 mallocand.I freedetect such corruption, they abort.