| <head> |
| <title>malloc(3) - Plan 9 from User Space</title> |
| <meta content="text/html; charset=utf-8" http-equiv=Content-Type> |
| </head> |
| <body bgcolor=#ffffff> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=10><td> |
| <tr><td width=20><td> |
| <tr><td width=20><td><b>MALLOC(3)</b><td align=right><b>MALLOC(3)</b> |
| <tr><td width=20><td colspan=2> |
| <br> |
| <p><font size=+1><b>NAME </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| malloc, mallocz, free, realloc, calloc, setmalloctag, setrealloctag, |
| getmalloctag, getrealloctag – memory allocator<br> |
| |
| </table> |
| <p><font size=+1><b>SYNOPSIS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>#include <u.h><br> |
| #include <libc.h> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void* malloc(ulong size) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void* mallocz(ulong size, int clr) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void free(void *ptr) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void* realloc(void *ptr, ulong size) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void* calloc(ulong nelem, ulong elsize) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void setmalloctag(void *ptr, ulong tag) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>ulong getmalloctag(void *ptr) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>void setrealloctag(void *ptr, ulong tag) |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| </font></tt> |
| <tt><font size=+1>ulong getrealloctag(void *ptr)<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>DESCRIPTION </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <i>Malloc</i> and <i>free</i> provide a simple memory allocation package. <i>Malloc</i> |
| returns a pointer to a new block of at least <i>size</i> bytes. The block |
| is suitably aligned for storage of any type of object. No two |
| active pointers from <i>malloc</i> will have the same value. The call |
| <tt><font size=+1>malloc(0)</font></tt> returns a valid pointer rather than null. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The argument to <i>free</i> is a pointer to a block previously allocated |
| by <i>malloc</i>; 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</i> are undefined. <i>Mallocz</i> |
| behaves as <i>malloc</i>, except that if <i>clr</i> is non-zero, the memory |
| returned will be zeroed. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| <i>Realloc</i> changes the size of the block pointed to by <i>ptr</i> to <i>size</i> |
| 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</i> takes on special meanings when one or both arguments |
| are zero:<br> |
| <tt><font size=+1>realloc(0, size)<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| means <tt><font size=+1>malloc(size)</font></tt>; returns a pointer to the newly-allocated memory<br> |
| |
| </table> |
| <tt><font size=+1>realloc(ptr, 0)<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| means <tt><font size=+1>free(ptr)</font></tt>; returns null<br> |
| |
| </table> |
| <tt><font size=+1>realloc(0, 0)<br> |
| </font></tt> |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| no-op; returns null |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| |
| </table> |
| <i>Calloc</i> allocates space for an array of <i>nelem</i> elements of size |
| <i>elsize</i>. The space is initialized to zeros. <i>Free</i> frees such a block. |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| 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 <i>setmalloctag</i>, <i>getmalloctag</i>, |
| <i>setrealloctag</i>, and <i>getrealloctag</i>. When allocating blocks directly |
| with <i>malloc</i> and <i>realloc</i>, 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 <a href="../man3/getcallerpc.html"><i>getcallerpc</i>(3)</a> |
| to <i>setmalloctag</i>) to provide more useful information about the |
| source |
| of allocation.<br> |
| |
| </table> |
| <p><font size=+1><b>SOURCE </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <tt><font size=+1>/usr/local/plan9/src/lib9/malloc.c<br> |
| /usr/local/plan9/src/lib9/malloctag.c<br> |
| </font></tt> |
| </table> |
| <p><font size=+1><b>SEE ALSO </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <i>trump</i> (in <a href="../man1/acid.html"><i>acid</i>(1)</a>), <a href="../man3/getcallerpc.html"><i>getcallerpc</i>(3)</a><br> |
| |
| </table> |
| <p><font size=+1><b>DIAGNOSTICS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| <i>Malloc, realloc</i> and <i>calloc</i> return 0 if there is no available memory. |
| <i>Errstr</i> is likely to be set. If the allocated blocks have no malloc |
| or realloc tags, <i>getmalloctag</i> and <i>getrealloctag</i> return <tt><font size=+1>~0</font></tt>. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| The <i>trump</i> library for <i>acid</i> can be used to obtain traces of malloc |
| execution; see <a href="../man1/acid.html"><i>acid</i>(1)</a>.<br> |
| |
| </table> |
| <p><font size=+1><b>BUGS </b></font><br> |
| |
| <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> |
| |
| The different specification of <i>calloc</i> is bizarre. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| 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</i> and <i>free</i> detect such |
| corruption, they abort. |
| <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> |
| |
| To avoid name conflicts with the system versions of these functions, |
| <i>malloc</i>, <i>realloc</i>, <i>calloc</i>, and <i>free</i> are preprocessor macros defined |
| as <i>p9malloc</i>, <i>p9realloc</i>, <i>p9calloc</i>, and <i>p9free</i>; see <a href="../man3/intro.html"><i>intro</i>(3)</a>.<br> |
| |
| </table> |
| |
| <td width=20> |
| <tr height=20><td> |
| </table> |
| <!-- TRAILER --> |
| <table border=0 cellpadding=0 cellspacing=0 width=100%> |
| <tr height=15><td width=10><td><td width=10> |
| <tr><td><td> |
| <center> |
| <a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> |
| </center> |
| </table> |
| <!-- TRAILER --> |
| </body></html> |
