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 May 2, 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.Fn calloc 200is directly supported by keeping track of newly-allocated zones which 201will be demand-zero'd by the system. 202If the allocation is known to be zero'd we do not bother 203.Fn bzero Ns ing 204it. 205If it is a reused allocation we 206.Fn bzero . 207.Pp 208.Tn POSIX 209threading is supported by duplicating the primary structure. 210A thread entering 211.Fn malloc 212which is unable to immediately acquire a mutex on the last primary 213structure it used will switch to a different primary structure. 214At the moment this is more of a quick hack than a solution, but it works. 215.Sh RETURN VALUES 216The 217.Fn malloc 218and 219.Fn calloc 220functions return a pointer to the allocated memory if successful; otherwise 221a 222.Dv NULL 223pointer is returned and 224.Va errno 225is set to 226.Er ENOMEM . 227.Pp 228The 229.Fn realloc 230and 231.Fn reallocf 232functions return a pointer, possibly identical to 233.Fa ptr , 234to the allocated memory 235if successful; otherwise a 236.Dv NULL 237pointer is returned, and 238.Va errno 239is set to 240.Er ENOMEM 241if the error was the result of an allocation failure. 242The 243.Fn realloc 244function always leaves the original buffer intact 245when an error occurs, whereas 246.Fn reallocf 247deallocates it in this case. 248.Pp 249The 250.Fn free 251function returns no value. 252.Sh DIAGNOSTIC MESSAGES 253If 254.Fn malloc , 255.Fn calloc , 256.Fn realloc 257or 258.Fn free 259detect an error, a message will be printed to file descriptor 260.Dv STDERR_FILENO 261and the process will dump core. 262.Sh SEE ALSO 263.Xr brk 2 , 264.Xr mmap 2 , 265.Xr alloca 3 , 266.Xr getpagesize 3 , 267.Xr memory 3 , 268.Xr posix_memalign 3 269.Sh STANDARDS 270The 271.Fn malloc , 272.Fn calloc , 273.Fn realloc 274and 275.Fn free 276functions conform to 277.St -isoC . 278.Sh HISTORY 279The present allocation implementation started out as a filesystem for a 280drum attached to a 20bit binary challenged computer which was built 281with discrete germanium transistors. 282It has since graduated to handle primary storage rather than secondary. 283.Pp 284The 285.Fn reallocf 286function first appeared in 287.Fx 3.0 . 288.Pp 289.Dx Ap s 290current 291.Nm 292implementation is a complete rewrite based on the kernel's slab allocator (see 293.Xr posix_memalign 3 Ap s 294.Sx IMPLEMENTATION NOTES ) . 295It first appeared in 296.Dx 2.3 . 297.Sh AUTHORS 298.An Matt Dillon 299