181 lines
7.9 KiB
HTML
181 lines
7.9 KiB
HTML
<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>
|