ref: 8a234e57b92f0915aae935aa0c9fe5285113b32f
dir: /sys/man/9/malloc/
.TH MALLOC 9 .SH NAME malloc, mallocz, smalloc, realloc, free, msize, secalloc, secfree, setmalloctag, setrealloctag, getmalloctag, getrealloctag \- kernel memory allocator .SH SYNOPSIS .ta \w'\fLvoid* 'u .B void* malloc(ulong size) .PP .B void* mallocalign(ulong size, ulong align, long offset, ulong span) .PP .B void* mallocz(ulong size, int clr) .PP .B void* smalloc(ulong size) .PP .B void* realloc(void *p, ulong size) .PP .B void free(void *ptr) .PP .B ulong msize(void *ptr) .PP .B void* secalloc(ulong size) .PP .B void secfree(void *ptr) .PP .B void setmalloctag(void *ptr, ulong tag) .PP .B ulong getmalloctag(void *ptr) .PP .B void setrealloctag(void *ptr, ulong tag) .PP .B ulong getrealloctag(void *ptr) .PP .SH DESCRIPTION These are kernel versions of the functions in .IR malloc (2). They allocate memory from the .B mainmem memory pool, which is managed by the allocator .IR pool (2), which in turn replenishes the pool as required by calling .IR xalloc (9). All but .I smalloc (which calls .IR sleep (9)) may safely be called by interrupt handlers. .PP .I Malloc returns a pointer to a block of at least .I size bytes, initialised to zero. The block is suitably aligned for storage of any type of object. The call .B malloc(0) returns a valid pointer rather than null. .I Mallocz is similar, but only clears the memory if .I clr is non-zero. .PP .I Smalloc returns a pointer to a block of .I size bytes, initialised to zero. If the memory is not immediately available, .I smalloc retries every 100 milliseconds until the memory is acquired. .PP .I Mallocalign allocates a block of at least .I n bytes of memory respecting alignment contraints. If .I align is non-zero, the returned pointer is aligned to be equal to .I offset modulo .IR align . If .I span is non-zero, the .I n byte block allocated will not span a .IR span -byte boundary. .PP .I Realloc changes the size of the block pointed to by .I p to .I size bytes, if possible without moving the data, and returns a pointer to the block. The contents are unchanged up to the lesser of old and new sizes, and any new space allocated is initialised to zero. .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 The argument to .I free is a pointer to a block of memory allocated by one of the routines above, which is returned to the allocation pool, or a null pointer, which is ignored. .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 .I Secalloc and .I secfree are security-aware functions that use a pool flagged by .B POOL_ANTAGONISM (see .IR pool (2)), which fills every allocated block with garbage before and after its use, to prevent leakage. .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. .SH SOURCE .B /sys/src/9/port/alloc.c .SH DIAGNOSTICS All functions except .I smalloc return a null pointer if space is unavailable. If the allocated blocks have no malloc or realloc tags, .I getmalloctag and .I getrealloctag return .BR ~0 . .SH SEE ALSO .IR pool (2), .IR xalloc (9)