usr/src/man/man3c/malloc.3c

   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
  75 The
  76 .Fn malloc
  77 and
  78 .Fn free
  79 functions provide a simple, general-purpose memory allocation package.
  80 The
  81 .Fn malloc
  82 function returns a pointer to a block of at least
  83 .Fa size
  84 bytes suitably aligned for any use.
  85 If the space assigned by
  86 .Fn malloc
  87 is overrun, the results are undefined.
  88 .Pp
  89 The argument to
  90 .Fn free
  91 is a pointer to a block previously allocated by
  92 .Fn malloc ,
  93 .Fn calloc ,
  94 .Fn realloc ,
  95 or
  96 .Fn reallocarray .
  97 After
  98 .Fn free
  99 is executed, this space is made available for further allocation by the
 100 application, though not returned to the system.
 101 Memory is returned to the system only upon termination of the application.
 102 If
 103 .Fa ptr
 104 is a null pointer, no action occurs.
 105 If a random number is passed to
 106 .Fn free ,
 107 the results are undefined.
 108 .Pp
 109 The
 110 .Fn calloc
 111 function allocates space for an array of
 112 .Fa nelem
 113 elements of size
 114 .Fa elsize .
 115 The space is initialized to zeros.
 116 .Pp
 117 The
 118 .Fn memalign
 119 function allocates
 120 .Fa size
 121 bytes on a specified alignment boundary and returns a pointer to the allocated
 122 block.
 123 The value of the returned address is guaranteed to be an even multiple of
 124 .Fa alignment .
 125 The value of
 126 .Fa alignment
 127 must be a power of two and must be greater than or equal to the size of a word.
 128 .Pp
 129 The
 130 .Fn realloc
 131 function changes the size of the block pointed to by
 132 .Fa ptr
 133 to
 134 .Fa size
 135 bytes and returns a pointer to the
 136 .Pq possibly moved
 137 block.
 138 The contents will be unchanged up to the lesser of the new and old sizes.
 139 If the new size of the block requires movement of the block, the space for the
 140 previous instantiation of the block is freed.
 141 If the new size is larger, the contents of the newly allocated portion of the
 142 block are unspecified.
 143 If
 144 .Fa ptr
 145 is
 146 .Dv NULL ,
 147 .Fn realloc
 148 behaves like
 149 .Fn malloc
 150 for the specified size.
 151 If
 152 .Fa size
 153 is 0 and
 154 .Fa ptr
 155 is not a null pointer, the space pointed to is freed.
 156 .Pp
 157 The
 158 .Fn reallocarray
 159 function is similar to
 160 .Fn realloc ,
 161 but operates on
 162 .Fa nelem
 163 elements of size
 164 .Fa elsize
 165 and checks for overflow in
 166 .Fa nelem Ns * Ns Fa elsize
 167 calculation.
 168 .Pp
 169 The
 170 .Fn valloc
 171 function has the same effect as
 172 .Fn malloc ,
 173 except that the allocated memory will be aligned to a multiple of the value
 174 returned by
 175 .Nm sysconf Ns Pq Dv _SC_PAGESIZE .
 176 .Pp
 177 The
 178 .Fn alloca
 179 function allocates
 180 .Fa size
 181 bytes of space in the stack frame of the caller, and returns a pointer to the
 182 allocated block.
 183 This temporary space is automatically freed when the caller returns.
 184 If the allocated block is beyond the current stack limit, the resulting behavior
 185 is undefined.
 186 .Sh RETURN VALUES
 187 Upon successful completion, each of the allocation functions returns a pointer
 188 to space suitably aligned
 189 .Pq after possible pointer coercion
 190 for storage of any type of object.
 191 .Pp
 192 If there is no available memory,
 193 .Fn malloc ,
 194 .Fn realloc ,
 195 .Fn reallocarray ,
 196 .Fn memalign ,
 197 .Fn valloc ,
 198 and
 199 .Fn calloc
 200 return a null pointer.
 201 .Pp
 202 When
 203 .Fn realloc
 204 or
 205 .Fn reallocarray
 206 is called with
 207 .Fa size
 208 > 0 and returns
 209 .Dv NULL ,
 210 the block pointed to by
 211 .Fa ptr
 212 is left intact.
 213 If
 214 .Fa size ,
 215 .Fa nelem ,
 216 or
 217 .Fa elsize
 218 is 0, either a null pointer or a unique pointer that can be passed to
 219 .Fn free
 220 is returned.
 221 .Pp
 222 If
 223 .Fn malloc ,
 224 .Fn calloc ,
 225 .Fn realloc ,
 226 or
 227 .Fn reallocarray
 228 returns unsuccessfully,
 229 .Va errno
 230 will be set to indicate the error.
 231 The
 232 .Fn free
 233 function does not set
 234 .Va errno .
 235 .Sh ERRORS
 236 The
 237 .Fn malloc ,
 238 .Fn calloc ,
 239 .Fn realloc ,
 240 and
 241 .Fn reallocarray
 242 functions will fail if:
 243 .Bl -tag -width "ENOMEM"
 244 .It Er ENOMEM
 245 The physical limits of the system are exceeded by
 246 .Fa size
 247 bytes of memory which cannot be allocated, or there's integer overflow in
 248 .Fn reallocarray .
 249 .It Er EAGAIN
 250 There is not enough memory available to allocate
 251 .Fa size
 252 bytes of memory; but the application could try again later.
 253 .El
 254 .Sh USAGE
 255 Portable applications should avoid using
 256 .Fn valloc
 257 but should instead use
 258 .Fn malloc
 259 or
 260 .Xr mmap 2 .
 261 On systems with a large page size, the number of successful
 262 .Fn valloc
 263 operations might be 0.
 264 .Pp
 265 These default memory allocation routines are safe for use in multithreaded
 266 applications but are not scalable.
 267 Concurrent accesses by multiple threads are single-threaded through the use of a
 268 single lock.
 269 Multithreaded applications that make heavy use of dynamic memory allocation
 270 should be linked with allocation libraries designed for concurrent access, such
 271 as
 272 .Xr libumem 3LIB
 273 or
 274 .Xr libmtmalloc 3LIB .
 275 Applications that want to avoid using heap allocations
 276 .Pq with Xr brk 2
 277 can do so by using either
 278 .Xr libumem 3LIB
 279 or
 280 .Xr libmapmalloc 3LIB .
 281 The allocation libraries
 282 .Xr libmalloc 3LIB
 283 and
 284 .Xr libbsdmalloc 3LIB
 285 are available for special needs.
 286 .Pp
 287 Comparative features of the various allocation libraries can be found in the
 288 .Xr umem_alloc 3MALLOC
 289 manual page.
 290 .Sh INTERFACE STABILITY
 291 The
 292 .Fn malloc ,
 293 .Fn calloc ,
 294 .Fn free ,
 295 .Fn realloc ,
 296 .Fn valloc
 297 functions are
 298 .Sy Standard.
 299 .Pp
 300 The
 301 .Fn reallocarray
 302 function is
 303 .Sy Committed .
 304 .Pp
 305 The
 306 .Fn memalign
 307 and
 308 .Fn alloca
 309 functions 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
 325 Undefined results will occur if the size requested for a block of memory
 326 exceeds the maximum size of a process's heap, which can be obtained with
 327 .Xr getrlimit 2 .
 328 .Pp
 329 The
 330 .Fn alloca
 331 function is machine-, compiler-, and most of all, system-dependent.
 332 Its use is strongly discouraged.