| .TH MALLOC 3 |
| .SH NAME |
| malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, getmalloctag, getrealloctag \- 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 |
| 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) |
| .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 |
| 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 |
| .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 (3) |
| to |
| .IR setmalloctag ) |
| to provide more useful information about |
| the source of allocation. |
| .SH SOURCE |
| .B \*9/src/lib9/malloc.c |
| .br |
| .B \*9/src/lib9/malloctag.c |
| .SH SEE ALSO |
| .I trump |
| (in |
| .IR acid (1)), |
| .IR getcallerpc (3) |
| .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 |
| 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. |
| .PP |
| To avoid name conflicts with the system versions of these functions, |
| .IR malloc , |
| .IR realloc , |
| .IR calloc , |
| and |
| .I free |
| are preprocessor macros defined as |
| .IR p9malloc , |
| .IR p9realloc , |
| .IR p9calloc , |
| and |
| .IR p9free ; |
| see |
| .IR intro (3). |