1 .TH MALLOC 3
2 .SH NAME
3 malloc, mallocz, free, realloc, calloc, msize, setmalloctag, setrealloctag, getmalloctag, getrealloctag, malloctopoolblock \- memory allocator
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .ta \w'\fLvoid* 'u
10 .B
11 void*	malloc(ulong size)
12 .PP
13 .B
14 void*	mallocz(ulong size, int clr)
15 .PP
16 .B
17 void	free(void *ptr)
18 .PP
19 .B
20 void*	realloc(void *ptr, ulong size)
21 .PP
22 .B
23 void*	calloc(ulong nelem, ulong elsize)
24 .PP
25 .B
26 ulong	msize(void *ptr)
27 .PP
28 .B
29 void	setmalloctag(void *ptr, ulong tag)
30 .PP
31 .B
32 ulong	getmalloctag(void *ptr, ulong tag)
33 .PP
34 .B
35 void	setrealloctag(void *ptr, ulong tag)
36 .PP
37 .B
38 ulong	getrealloctag(void *ptr, ulong tag)
39 .PP
40 .B
41 void*	malloctopoolblock(void*)
42 .PP
43 .SH DESCRIPTION
44 .I Malloc
45 and
46 .I free
47 provide a simple memory allocation package.
48 .I Malloc
49 returns a pointer to a new block of at least
50 .I size
51 bytes.
52 The block is suitably aligned for storage of any type of object.
53 No two active pointers from
54 .I malloc
55 will have the same value.
56 The call
57 .B malloc(0)
58 returns a valid pointer rather than null.
59 .PP
60 The argument to
61 .I free
62 is a pointer to a block previously allocated by
63 .IR malloc ;
64 this space is made available for further allocation.
65 It is legal to free a null pointer; the effect is a no-op.
66 The contents of the space returned by
67 .I malloc
68 are undefined.
69 .I Mallocz
70 behaves as 
71 .IR malloc ,
72 except that if 
73 .I clr
74 is non-zero, the memory returned will be zeroed.
75 .PP
76 .I Realloc
77 changes the size of the block pointed to by
78 .I ptr
79 to
80 .I size
81 bytes and returns a pointer to the (possibly moved)
82 block.
83 The contents will be unchanged up to the
84 lesser of the new and old sizes.
85 .I Realloc
86 takes on special meanings when one or both arguments are zero:
87 .TP
88 .B "realloc(0,\ size)
89 means
90 .LR malloc(size) ;
91 returns a pointer to the newly-allocated memory
92 .TP
93 .B "realloc(ptr,\ 0)
94 means
95 .LR free(ptr) ;
96 returns null
97 .TP
98 .B "realloc(0,\ 0)
99 no-op; returns null
100 .PD
101 .PP
102 .I Calloc
103 allocates space for
104 an array of
105 .I nelem
106 elements of size
107 .IR elsize .
108 The space is initialized to zeros.
109 .I Free
110 frees such a block.
111 .PP
112 When a block is allocated, sometimes there is some extra unused space at the end.
113 .I Msize
114 grows the block to encompass this unused space and returns the new number
115 of bytes that may be used.
116 .PP
117 The memory allocator maintains two word-sized fields
118 associated with each block, the ``malloc tag'' and the ``realloc tag''.
119 By convention, the malloc tag is the PC that allocated the block,
120 and the realloc tag the PC that last reallocated the block.
121 These may be set or examined with 
122 .IR setmalloctag ,
123 .IR getmalloctag ,
124 .IR setrealloctag ,
125 and
126 .IR getrealloctag .
127 When allocating blocks directly with
128 .I malloc
129 and
130 .IR realloc ,
131 these tags will be set properly.
132 If a custom allocator wrapper is used,
133 the allocator wrapper can set the tags
134 itself (usually by passing the result of
135 .IR getcallerpc (3) 
136 to 
137 .IR setmalloctag )
138 to provide more useful information about
139 the source of allocation.
140 .PP
141 .I Malloctopoolblock
142 takes the address of a block returned by
143 .I malloc
144 and returns the address of the corresponding
145 block allocated by the
146 .IR pool (3)
147 routines.
148 .SH SOURCE
149 .B /usr/local/plan9/src/libc/port/malloc.c
150 .SH SEE ALSO
151 .IR leak (1),
152 .I trump
153 (in
154 .IR acid (1)),
155 .IR brk (3),
156 .IR getcallerpc (3),
157 .IR pool (3)
158 .SH DIAGNOSTICS
159 .I Malloc, realloc
160 and
161 .I calloc
162 return 0 if there is no available memory.
163 .I Errstr
164 is likely to be set.
165 If the allocated blocks have no malloc or realloc tags,
166 .I getmalloctag
167 and
168 .I getrealloctag
169 return
170 .BR ~0 .
171 .PP
172 After including
173 .BR pool.h ,
174 the call
175 .B poolcheck(mainmem)
176 can be used to scan the storage arena for inconsistencies
177 such as data written beyond the bounds of allocated blocks.
178 It is often useful to combine this with with setting
179 .EX
180     mainmem->flags |= POOL_NOREUSE;
181 .EE
182 at the beginning of your program.
183 This will cause malloc not to reallocate blocks even
184 once they are freed;
185 .B poolcheck(mainmem)
186 will then detect writes to freed blocks.
187 .PP
188 The 
189 .I trump
190 library for
191 .I acid
192 can be used to obtain traces of malloc execution; see
193 .IR acid (1).
194 .SH BUGS
195 The different specification of
196 .I calloc
197 is bizarre.
198 .PP
199 User errors can corrupt the storage arena.
200 The most common gaffes are (1) freeing an already freed block,
201 (3) storing beyond the bounds of an allocated block, and (3)
202 freeing data that was not obtained from the allocator.
203 When
204 .I malloc
205 and
206 .I free
207 detect such corruption, they abort.