1.\" 2.\" The contents of this file are subject to the terms of the 3.\" Common Development and Distribution License (the "License"). 4.\" You may not use this file except in compliance with the License. 5.\" 6.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 7.\" or http://www.opensolaris.org/os/licensing. 8.\" See the License for the specific language governing permissions 9.\" and limitations under the License. 10.\" 11.\" When distributing Covered Code, include this CDDL HEADER in each 12.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 13.\" If applicable, add the following below this CDDL HEADER, with the 14.\" fields enclosed by brackets "[]" replaced with your own identifying 15.\" information: Portions Copyright [yyyy] [name of copyright owner] 16.\" 17.\" 18.\" Copyright 1989 AT&T 19.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved. 20.\" 21.Dd March 10, 2017 22.Dt MALLOC 3C 23.Os 24.Sh NAME 25.Nm malloc , 26.Nm calloc , 27.Nm free , 28.Nm memalign , 29.Nm realloc , 30.Nm reallocarray , 31.Nm valloc , 32.Nm alloca 33.Nd memory allocator 34.Sh SYNOPSIS 35.In stdlib.h 36.Ft void * 37.Fo malloc 38.Fa "size_t size" 39.Fc 40.Ft void * 41.Fo calloc 42.Fa "size_t nelem" 43.Fa "size_t elsize" 44.Fc 45.Ft void 46.Fo free 47.Fa "void *ptr" 48.Fc 49.Ft void * 50.Fo memalign 51.Fa "size_t alignment" 52.Fa "size_t size" 53.Fc 54.Ft void * 55.Fo realloc 56.Fa "void *ptr" 57.Fa "size_t size" 58.Fc 59.Ft void * 60.Fo reallocarray 61.Fa "void *ptr" 62.Fa "size_t nelem" 63.Fa "size_t elsize" 64.Fc 65.Ft void * 66.Fo valloc 67.Fa "size_t size" 68.Fc 69.In alloca.h 70.Ft void * 71.Fo alloca 72.Fa "size_t size" 73.Fc 74.Sh DESCRIPTION 75The 76.Fn malloc 77and 78.Fn free 79functions provide a simple, general-purpose memory allocation package. 80The 81.Fn malloc 82function returns a pointer to a block of at least 83.Fa size 84bytes suitably aligned for any use. 85If the space assigned by 86.Fn malloc 87is overrun, the results are undefined. 88.Pp 89The argument to 90.Fn free 91is a pointer to a block previously allocated by 92.Fn malloc , 93.Fn calloc , 94.Fn realloc , 95or 96.Fn reallocarray . 97After 98.Fn free 99is executed, this space is made available for further allocation by the 100application, though not returned to the system. 101Memory is returned to the system only upon termination of the application. 102If 103.Fa ptr 104is a null pointer, no action occurs. 105If a random number is passed to 106.Fn free , 107the results are undefined. 108.Pp 109The 110.Fn calloc 111function allocates space for an array of 112.Fa nelem 113elements of size 114.Fa elsize . 115The space is initialized to zeros. 116.Pp 117The 118.Fn memalign 119function allocates 120.Fa size 121bytes on a specified alignment boundary and returns a pointer to the allocated 122block. 123The value of the returned address is guaranteed to be an even multiple of 124.Fa alignment . 125The value of 126.Fa alignment 127must be a power of two and must be greater than or equal to the size of a word. 128.Pp 129The 130.Fn realloc 131function changes the size of the block pointed to by 132.Fa ptr 133to 134.Fa size 135bytes and returns a pointer to the 136.Pq possibly moved 137block. 138The contents will be unchanged up to the lesser of the new and old sizes. 139If the new size of the block requires movement of the block, the space for the 140previous instantiation of the block is freed. 141If the new size is larger, the contents of the newly allocated portion of the 142block are unspecified. 143If 144.Fa ptr 145is 146.Dv NULL , 147.Fn realloc 148behaves like 149.Fn malloc 150for the specified size. 151If 152.Fa size 153is 0 and 154.Fa ptr 155is not a null pointer, the space pointed to is freed. 156.Pp 157The 158.Fn reallocarray 159function is similar to 160.Fn realloc , 161but operates on 162.Fa nelem 163elements of size 164.Fa elsize 165and checks for overflow in 166.Fa nelem Ns * Ns Fa elsize 167calculation. 168.Pp 169The 170.Fn valloc 171function has the same effect as 172.Fn malloc , 173except that the allocated memory will be aligned to a multiple of the value 174returned by 175.Nm sysconf Ns Pq Dv _SC_PAGESIZE . 176.Pp 177The 178.Fn alloca 179function allocates 180.Fa size 181bytes of space in the stack frame of the caller, and returns a pointer to the 182allocated block. 183This temporary space is automatically freed when the caller returns. 184If the allocated block is beyond the current stack limit, the resulting behavior 185is undefined. 186.Sh RETURN VALUES 187Upon successful completion, each of the allocation functions returns a pointer 188to space suitably aligned 189.Pq after possible pointer coercion 190for storage of any type of object. 191.Pp 192If there is no available memory, 193.Fn malloc , 194.Fn realloc , 195.Fn reallocarray , 196.Fn memalign , 197.Fn valloc , 198and 199.Fn calloc 200return a null pointer. 201.Pp 202When 203.Fn realloc 204or 205.Fn reallocarray 206is called with 207.Fa size 208> 0 and returns 209.Dv NULL , 210the block pointed to by 211.Fa ptr 212is left intact. 213If 214.Fa size , 215.Fa nelem , 216or 217.Fa elsize 218is 0, either a null pointer or a unique pointer that can be passed to 219.Fn free 220is returned. 221.Pp 222If 223.Fn malloc , 224.Fn calloc , 225.Fn realloc , 226or 227.Fn reallocarray 228returns unsuccessfully, 229.Va errno 230will be set to indicate the error. 231The 232.Fn free 233function does not set 234.Va errno . 235.Sh ERRORS 236The 237.Fn malloc , 238.Fn calloc , 239.Fn realloc , 240and 241.Fn reallocarray 242functions will fail if: 243.Bl -tag -width "ENOMEM" 244.It Er ENOMEM 245The physical limits of the system are exceeded by 246.Fa size 247bytes of memory which cannot be allocated, or there's integer overflow in 248.Fn reallocarray . 249.It Er EAGAIN 250There is not enough memory available to allocate 251.Fa size 252bytes of memory; but the application could try again later. 253.El 254.Sh USAGE 255Portable applications should avoid using 256.Fn valloc 257but should instead use 258.Fn malloc 259or 260.Xr mmap 2 . 261On systems with a large page size, the number of successful 262.Fn valloc 263operations might be 0. 264.Pp 265These default memory allocation routines are safe for use in multithreaded 266applications but are not scalable. 267Concurrent accesses by multiple threads are single-threaded through the use of a 268single lock. 269Multithreaded applications that make heavy use of dynamic memory allocation 270should be linked with allocation libraries designed for concurrent access, such 271as 272.Xr libumem 3LIB 273or 274.Xr libmtmalloc 3LIB . 275Applications that want to avoid using heap allocations 276.Pq with Xr brk 2 277can do so by using either 278.Xr libumem 3LIB 279or 280.Xr libmapmalloc 3LIB . 281The allocation libraries 282.Xr libmalloc 3LIB 283and 284.Xr libbsdmalloc 3LIB 285are available for special needs. 286.Pp 287Comparative features of the various allocation libraries can be found in the 288.Xr umem_alloc 3MALLOC 289manual page. 290.Sh INTERFACE STABILITY 291The 292.Fn malloc , 293.Fn calloc , 294.Fn free , 295.Fn realloc , 296.Fn valloc 297functions are 298.Sy Standard. 299.Pp 300The 301.Fn reallocarray 302function is 303.Sy Committed . 304.Pp 305The 306.Fn memalign 307and 308.Fn alloca 309functions are 310.Sy Stable . 311.Sh MT-LEVEL 312.Sy Safe. 313.Sh SEE ALSO 314.Xr brk 2 , 315.Xr getrlimit 2 , 316.Xr libbsdmalloc 3LIB , 317.Xr libmalloc 3LIB , 318.Xr libmapmalloc 3LIB , 319.Xr libmtmalloc 3LIB , 320.Xr libumem 3LIB , 321.Xr umem_alloc 3MALLOC , 322.Xr watchmalloc 3MALLOC , 323.Xr attributes 5 324.Sh WARNINGS 325Undefined results will occur if the size requested for a block of memory 326exceeds the maximum size of a process's heap, which can be obtained with 327.Xr getrlimit 2 . 328.Pp 329The 330.Fn alloca 331function is machine-, compiler-, and most of all, system-dependent. 332Its use is strongly discouraged. 333