1.\" $NetBSD: malloc.3,v 1.39 2015/02/05 16:04:35 christos Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the American National Standards Committee X3, on Information 8.\" Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93 35.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $ 36.\" 37.Dd February 5, 2015 38.Dt MALLOC 3 39.Os 40.Sh NAME 41.Nm malloc , calloc , realloc , reallocarray, free 42.Nd general purpose memory allocation functions 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In stdlib.h 47.Ft void * 48.Fn malloc "size_t size" 49.Ft void * 50.Fn calloc "size_t number" "size_t size" 51.Ft void * 52.Fn realloc "void *ptr" "size_t size" 53.Ft void * 54.Fn reallocarray "void *ptr" "size_t number" "size_t size" 55.Ft void 56.Fn free "void *ptr" 57.Sh DESCRIPTION 58The 59.Fn malloc 60function allocates 61.Fa size 62bytes of uninitialized memory. 63The allocated space is suitably aligned (after possible pointer coercion) 64for storage of any type of object. 65.Pp 66The 67.Fn calloc 68function allocates space for 69.Fa number 70objects, 71each 72.Fa size 73bytes in length. 74The result is identical to calling 75.Fn malloc 76with an argument of 77.Dq "number * size" , 78with the exception that the allocated memory is explicitly initialized 79to zero bytes, and overflow is being checked. 80.Pp 81The 82.Fn realloc 83function changes the size of the previously allocated memory referenced by 84.Fa ptr 85to 86.Fa size 87bytes. 88The contents of the memory are unchanged up to the lesser of the new and 89old sizes. 90If the new size is larger, 91the value of the newly allocated portion of the memory is undefined. 92Upon success, the memory referenced by 93.Fa ptr 94is freed and a pointer to the newly allocated memory is returned. 95.Pp 96The 97.Fn reallocarray 98function is similar to 99.Fn realloc 100except it operates on 101.Fa number 102members of size 103.Fa size 104and checks for integer overflow in the calculation of\ 105.Dq "number * size" . 106.Pp 107Note that 108.Fn realloc 109and 110.Fn reallocarray 111may move the memory allocation, resulting in a different return value than 112.Fa ptr . 113If 114.Fa ptr 115is 116.Dv NULL , 117the 118.Fn realloc 119function behaves identically to 120.Fn malloc 121for the specified size. 122.Pp 123The 124.Fn free 125function causes the allocated memory referenced by 126.Fa ptr 127to be made available for future allocations. 128If 129.Fa ptr 130is 131.Dv NULL , 132no action occurs. 133.Sh RETURN VALUES 134The 135.Fn malloc 136and 137.Fn calloc 138functions return a pointer to the allocated memory if successful; otherwise 139a 140.Dv NULL 141pointer is returned and 142.Va errno 143is set to 144.Er ENOMEM . 145.Pp 146The 147.Fn realloc 148and 149.Fn reallocarray 150functions return a pointer, possibly identical to 151.Fa ptr , 152to the allocated memory 153if successful; otherwise a 154.Dv NULL 155pointer is returned, and 156.Va errno 157is set to 158.Er ENOMEM 159if the error was the result of an allocation failure. 160The 161.Fn realloc 162and 163.Fn reallocarray 164functions always leave the original buffer intact 165when an error occurs. 166.Pp 167The 168.Fn free 169function returns no value. 170.Sh EXAMPLES 171When using 172.Fn malloc , 173be careful to avoid the following idiom: 174.Bd -literal -offset indent 175if ((p = malloc(number * size)) == NULL) 176 err(EXIT_FAILURE, "malloc"); 177.Ed 178.Pp 179The multiplication may lead to an integer overflow. 180To avoid this, 181.Fn reallocarray 182is recommended. 183.Pp 184If 185.Fn malloc 186must be used, be sure to test for overflow: 187.Bd -literal -offset indent 188if (size && number > SIZE_MAX / size) { 189 errno = EOVERFLOW; 190 err(EXIT_FAILURE, "allocation"); 191} 192.Ed 193.Pp 194The above test is not sufficient in all cases. 195For example, multiplying ints requires a different set of checks: 196.Bd -literal -offset indent 197int num, size; 198\&.\&.\&. 199 200/* Avoid invalid requests */ 201if (size < 0 || num < 0) 202 errc(1, EOVERFLOW, "overflow"); 203 204/* Check for signed int overflow */ 205if (size && num > INT_MAX / size) 206 errc(1, EOVERFLOW, "overflow"); 207 208if ((p = malloc(size * num)) == NULL) 209 err(1, "malloc"); 210.Ed 211.Pp 212Assuming the implementation checks for integer overflow as 213.Nx 214does, it is much easier to use 215.Fn calloc 216or 217.Fn reallocarray . 218.Pp 219The above examples could be simplified to: 220.Bd -literal -offset indent 221if ((p = reallocarray(NULL, num, size)) == NULL) 222 err(1, "reallocarray"); 223.Ed 224.Bd -literal -offset indent 225or at the cost of initialization: 226if ((p = calloc(num, size)) == NULL) 227 err(1, "calloc"); 228.Ed 229.Pp 230When using 231.Fn realloc , 232one must be careful to avoid the following idiom: 233.Pp 234.Bd -literal -offset indent 235nsize += 50; 236 237if ((p = realloc(p, nsize)) == NULL) 238 return NULL; 239.Ed 240.Pp 241Do not adjust the variable describing how much memory has been allocated 242until it is known that the allocation has been successful. 243This can cause aberrant program behavior if the incorrect size value is used. 244In most cases, the above example will also leak memory. 245As stated earlier, a return value of 246.Dv NULL 247indicates that the old object still remains allocated. 248Better code looks like this: 249.Bd -literal -offset indent 250newsize = size + 50; 251 252if ((p2 = realloc(p, newsize)) == NULL) { 253 254 if (p != NULL) 255 free(p); 256 257 p = NULL; 258 return NULL; 259} 260 261p = p2; 262size = newsize; 263.Ed 264.Sh SEE ALSO 265.\" .Xr limits 1 , 266.Xr madvise 2 , 267.Xr mmap 2 , 268.Xr sbrk 2 , 269.Xr alloca 3 , 270.Xr atexit 3 , 271.Xr getpagesize 3 , 272.Xr memory 3 , 273.Xr posix_memalign 3 274.Pp 275For the implementation details, see 276.Xr jemalloc 3 . 277.Sh STANDARDS 278The 279.Fn malloc , 280.Fn calloc , 281.Fn realloc 282and 283.Fn free 284functions conform to 285.St -isoC . 286.Pp 287The 288.Fn reallocarray 289function first appeared on 290.Ox 5.6 291and 292.Nx 8 . 293