1 .\" Copyright (c) 1980, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" the American National Standards Committee X3, on Information
6 .\" Processing Systems.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed by the University of
19 .\" California, Berkeley and its contributors.
20 .\" 4. Neither the name of the University nor the names of its contributors
21 .\" may be used to endorse or promote products derived from this software
22 .\" without specific prior written permission.
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .\" @(#)malloc.3 8.1 (Berkeley) 6/4/93
37 .\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.25.2.16 2003/01/06 17:10:45 trhodes Exp $
38 .\" $DragonFly: src/lib/libc/stdlib/malloc.3,v 1.8 2008/05/02 02:05:04 swildner Exp $
49 .Nd general purpose memory allocation functions
55 .Fn malloc "size_t size"
57 .Fn calloc "size_t number" "size_t size"
59 .Fn realloc "void *ptr" "size_t size"
61 .Fn reallocf "void *ptr" "size_t size"
70 The allocated space is suitably aligned (after possible pointer coercion)
71 for storage of any type of object.
72 If the space is at least
76 the returned memory will be page boundary aligned as well.
87 normally initialize the returned memory to zero bytes.
91 function allocates space for
97 The result is identical to calling
100 .Dq Fa number * Fa size ,
101 with the exception that the allocated memory is explicitly initialized
106 function changes the size of the previously allocated memory referenced by
111 The contents of the memory are unchanged up to the lesser of the new and
113 If the new size is larger,
114 the value of the newly allocated portion of the memory is undefined.
115 If the requested memory cannot be allocated,
118 the memory referenced by
120 is valid and unchanged.
127 function behaves identically to
129 for the specified size.
133 function call is identical to the realloc function call, except that it
134 will free the passed pointer when the requested memory cannot be allocated.
139 specific API designed to ease the problems with traditional coding styles
140 for realloc causing memory leaks in libraries.
144 function causes the allocated memory referenced by
146 to be made available for future allocations.
152 .Sh IMPLEMENTATION NOTES
155 implementation is based on a port of the
157 kernel slab allocator, appropriately modified for a user process
160 The slab allocator breaks memory allocations up to 8KB into 80 zones.
161 Each zone represents a fixed allocation size in multiples of some
163 The chunking is a power-of-2 but the fixed allocation size is not.
164 For example, a 1025-byte request is allocated out of the zone with a
165 chunking of 128, thus in multiples of 1152 bytes.
166 The minimum chunking, used for allocations in the 0-127 byte range,
167 is 8 bytes (16 of the 80 zones).
168 Beyond that the power-of-2 chunking is between 1/8 and 1/16 of the
169 minimum allocation size for any given zone.
171 As a special case any power-of-2-sized allocation within the zone
172 limit (8K) will be aligned to the same power-of-2 rather than that
173 zone's (smaller) chunking.
174 This is not something you can depend upon for
176 but it is used internally to optimize
177 .Xr posix_memalign 3 .
179 Each zone reserves memory in 64KB blocks.
180 Actual memory use tends to be significantly less as only the pages
181 actually needed are faulted in.
182 Allocations larger than 8K are managed using
184 and tracked with a hash table.
186 The zone mechanism results in well-fitted allocations with little
187 waste in a long-running environment which makes a lot of allocations.
188 Short-running environments which do not make many allocations will see
189 a bit of extra bloat due to the large number of zones but it will
190 be almost unnoticeable in the grand scheme of things.
191 To reduce bloat further the normal randomized start offset implemented
192 in the kernel version of the allocator to improve L1 cache fill is
193 disabled in the libc version.
195 The zone mechanism also has the nice side effect of greatly reducing
196 fragmentation over the original
200 is directly supported by matching the requested alignment against a zone
201 with a compatible chunking, and using the power-of-2 shortcut whenever
203 Alignments beyond those supported by the zone mechanism are still
204 guaranteed using cute
209 is thus able to take advantage of the slab allocator to produce
210 well-fitted results when the requests are reasonable.
213 is directly supported by keeping track of newly-allocated zones which
214 will be demand-zero'd by the system.
215 If the allocation is known to be zero'd we do not bother
218 If it is a reused allocation we
222 threading is supported by duplicating the primary structure.
225 which is unable to immediately acquire a mutex on the last primary
226 structure it used will switch to a different primary structure.
227 At the moment this is more of a quick hack than a solution, but it works.
233 functions return a pointer to the allocated memory if successful; otherwise
236 pointer is returned and
245 functions return a pointer, possibly identical to
247 to the allocated memory
248 if successful; otherwise a
250 pointer is returned, and
254 if the error was the result of an allocation failure.
257 function always leaves the original buffer intact
258 when an error occurs, whereas
260 deallocates it in this case.
264 function returns no value.
265 .Sh DIAGNOSTIC MESSAGES
272 detect an error, a message will be printed to file descriptor
274 and the process will dump core.
291 The present allocation implementation started out as a filesystem for a
292 drum attached to a 20bit binary challenged computer which was built
293 with discrete germanium transistors.
294 It has since graduated to handle primary storage rather than secondary.
298 function first appeared in
304 implementation is a complete rewrite based on the kernel's slab allocator (see
305 .Sx IMPLEMENTATION NOTES ) .