1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
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>
|