1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" the American National Standards Committee X3, on Information 6.\" Processing Systems. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 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. 23.\" 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 34.\" SUCH DAMAGE. 35.\" 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 $ 39.\" 40.Dd April 30, 2009 41.Dt MALLOC 3 42.Os 43.Sh NAME 44.Nm malloc , 45.Nm calloc , 46.Nm realloc , 47.Nm free , 48.Nm reallocf 49.Nd general purpose memory allocation functions 50.Sh LIBRARY 51.Lb libc 52.Sh SYNOPSIS 53.In stdlib.h 54.Ft void * 55.Fn malloc "size_t size" 56.Ft void * 57.Fn calloc "size_t number" "size_t size" 58.Ft void * 59.Fn realloc "void *ptr" "size_t size" 60.Ft void * 61.Fn reallocf "void *ptr" "size_t size" 62.Ft void 63.Fn free "void *ptr" 64.Sh DESCRIPTION 65The 66.Fn malloc 67function allocates 68.Fa size 69bytes of memory. 70The allocated space is suitably aligned (after possible pointer coercion) 71for storage of any type of object. 72If the space is at least 73.Em pagesize 74bytes in length (see 75.Xr getpagesize 3 ) , 76the returned memory will be page boundary aligned as well. 77If 78.Fn malloc 79fails, a 80.Dv NULL 81pointer is returned. 82.Pp 83Note that 84.Fn malloc 85does 86.Em NOT 87normally initialize the returned memory to zero bytes. 88.Pp 89The 90.Fn calloc 91function allocates space for 92.Fa number 93objects, 94each 95.Fa size 96bytes in length. 97The result is identical to calling 98.Fn malloc 99with an argument of 100.Dq Fa number * Fa size , 101with the exception that the allocated memory is explicitly initialized 102to zero bytes. 103.Pp 104The 105.Fn realloc 106function changes the size of the previously allocated memory referenced by 107.Fa ptr 108to 109.Fa size 110bytes. 111The contents of the memory are unchanged up to the lesser of the new and 112old sizes. 113If the new size is larger, 114the value of the newly allocated portion of the memory is undefined. 115If the requested memory cannot be allocated, 116.Dv NULL 117is returned and 118the memory referenced by 119.Fa ptr 120is valid and unchanged. 121If 122.Fa ptr 123is 124.Dv NULL , 125the 126.Fn realloc 127function behaves identically to 128.Fn malloc 129for the specified size. 130.Pp 131The 132.Fn reallocf 133function call is identical to the realloc function call, except that it 134will free the passed pointer when the requested memory cannot be allocated. 135This is a 136.Fx 137/ 138.Dx 139specific API designed to ease the problems with traditional coding styles 140for realloc causing memory leaks in libraries. 141.Pp 142The 143.Fn free 144function causes the allocated memory referenced by 145.Fa ptr 146to be made available for future allocations. 147If 148.Fa ptr 149is 150.Dv NULL , 151no action occurs. 152.Sh IMPLEMENTATION NOTES 153.Dx Ap s 154.Nm 155implementation is based on a port of the 156.Dx 157kernel slab allocator, appropriately modified for a user process 158environment. 159.Pp 160The slab allocator breaks memory allocations up to 8KB into 80 zones. 161Each zone represents a fixed allocation size in multiples of some 162core chunking. 163The chunking is a power-of-2 but the fixed allocation size is not. 164For example, a 1025-byte request is allocated out of the zone with a 165chunking of 128, thus in multiples of 1152 bytes. 166The minimum chunking, used for allocations in the 0-127 byte range, 167is 8 bytes (16 of the 80 zones). 168Beyond that the power-of-2 chunking is between 1/8 and 1/16 of the 169minimum allocation size for any given zone. 170.Pp 171As a special case any power-of-2-sized allocation within the zone 172limit (8K) will be aligned to the same power-of-2 rather than that 173zone's (smaller) chunking. 174This is not something you can depend upon for 175.Fn malloc , 176but it is used internally to optimize 177.Xr posix_memalign 3 . 178.Pp 179Each zone reserves memory in 64KB blocks. 180Actual memory use tends to be significantly less as only the pages 181actually needed are faulted in. 182Allocations larger than 8K are managed using 183.Xr mmap 2 184and tracked with a hash table. 185.Pp 186The zone mechanism results in well-fitted allocations with little 187waste in a long-running environment which makes a lot of allocations. 188Short-running environments which do not make many allocations will see 189a bit of extra bloat due to the large number of zones but it will 190be almost unnoticeable in the grand scheme of things. 191To reduce bloat further the normal randomized start offset implemented 192in the kernel version of the allocator to improve L1 cache fill is 193disabled in the libc version. 194.Pp 195The zone mechanism also has the nice side effect of greatly reducing 196fragmentation over the original 197.Nm . 198.Pp 199.Xr posix_memalign 3 200is directly supported by matching the requested alignment against a zone 201with a compatible chunking, and using the power-of-2 shortcut whenever 202possible. 203Alignments beyond those supported by the zone mechanism are still 204guaranteed using cute 205.Xr mmap 2 206tricks. 207Our 208.Xr posix_memalign 3 209is thus able to take advantage of the slab allocator to produce 210well-fitted results when the requests are reasonable. 211.Pp 212.Fn calloc 213is directly supported by keeping track of newly-allocated zones which 214will be demand-zero'd by the system. 215If the allocation is known to be zero'd we do not bother 216.Fn bzero Ns ing 217it. 218If it is a reused allocation we 219.Fn bzero . 220.Pp 221.Tn POSIX 222threading is supported by duplicating the primary structure. 223A thread entering 224.Fn malloc 225which is unable to immediately acquire a mutex on the last primary 226structure it used will switch to a different primary structure. 227At the moment this is more of a quick hack than a solution, but it works. 228.Sh RETURN VALUES 229The 230.Fn malloc 231and 232.Fn calloc 233functions return a pointer to the allocated memory if successful; otherwise 234a 235.Dv NULL 236pointer is returned and 237.Va errno 238is set to 239.Er ENOMEM . 240.Pp 241The 242.Fn realloc 243and 244.Fn reallocf 245functions return a pointer, possibly identical to 246.Fa ptr , 247to the allocated memory 248if successful; otherwise a 249.Dv NULL 250pointer is returned, and 251.Va errno 252is set to 253.Er ENOMEM 254if the error was the result of an allocation failure. 255The 256.Fn realloc 257function always leaves the original buffer intact 258when an error occurs, whereas 259.Fn reallocf 260deallocates it in this case. 261.Pp 262The 263.Fn free 264function returns no value. 265.Sh DIAGNOSTIC MESSAGES 266If 267.Fn malloc , 268.Fn calloc , 269.Fn realloc 270or 271.Fn free 272detect an error, a message will be printed to file descriptor 273.Dv STDERR_FILENO 274and the process will dump core. 275.Sh SEE ALSO 276.Xr brk 2 , 277.Xr mmap 2 , 278.Xr alloca 3 , 279.Xr getpagesize 3 , 280.Xr memory 3 281.Sh STANDARDS 282The 283.Fn malloc , 284.Fn calloc , 285.Fn realloc 286and 287.Fn free 288functions conform to 289.St -isoC . 290.Sh HISTORY 291The present allocation implementation started out as a filesystem for a 292drum attached to a 20bit binary challenged computer which was built 293with discrete germanium transistors. 294It has since graduated to handle primary storage rather than secondary. 295.Pp 296The 297.Fn reallocf 298function first appeared in 299.Fx 3.0 . 300.Pp 301.Dx Ap s 302current 303.Nm 304implementation is a complete rewrite based on the kernel's slab allocator (see 305.Sx IMPLEMENTATION NOTES ) . 306It first appeared in 307.Dx 2.3 . 308.Sh AUTHORS 309.An Matt Dillon 310