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