diff options
Diffstat (limited to 'man/man3/malloc.html')
| -rw-r--r-- | man/man3/malloc.html | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/man/man3/malloc.html b/man/man3/malloc.html new file mode 100644 index 00000000..9c30c293 --- /dev/null +++ b/man/man3/malloc.html @@ -0,0 +1,181 @@ +<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> |