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