lib/libc/stdlib/malloc.3

   1 .\" $NetBSD: malloc.3,v 1.38 2010/05/03 08:23:20 jruoho 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. All advertising materials mentioning features or use of this software
  19 .\"    must display the following acknowledgement:
  20 .\"     This product includes software developed by the University of
  21 .\"     California, Berkeley and its contributors.
  22 .\" 4. Neither the name of the University nor the names of its contributors
  23 .\"    may be used to endorse or promote products derived from this software
  24 .\"    without specific prior written permission.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  27 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  28 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  29 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  30 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  31 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  32 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  33 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  34 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  35 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  36 .\" SUCH DAMAGE.
  37 .\"
  38 .\"     @(#)malloc.3    8.1 (Berkeley) 6/4/93
  39 .\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $
  40 .\"
  41 .Dd May 21, 2010
  42 .Dt MALLOC 3
  43 .Os
  44 .Sh NAME
  45 .Nm malloc ,
  46 .Nm calloc ,
  47 .Nm realloc ,
  48 .Nm reallocf ,
  49 .Nm free ,
  50 .Nd general purpose memory allocation functions
  51 .Sh LIBRARY
  52 .Lb libc
  53 .Sh SYNOPSIS
  54 .In stdlib.h
  55 .Ft void *
  56 .Fn malloc "size_t size"
  57 .Ft void *
  58 .Fn calloc "size_t number" "size_t size"
  59 .Ft void *
  60 .Fn realloc "void *ptr" "size_t size"
  61 .Ft void *
  62 .Fn reallocf "void *ptr" "size_t size"
  63 .Ft void
  64 .Fn free "void *ptr"
  65 .Sh DESCRIPTION
  66 The
  67 .Fn malloc
  68 function allocates
  69 .Fa size
  70 bytes of uninitialized memory.
  71 The allocated space is suitably aligned (after possible pointer coercion)
  72 for storage of any type of object.
  73 If the space is at least
  74 .Em pagesize
  75 bytes in length (see
  76 .Xr getpagesize 3 ) ,
  77 the returned memory will be page boundary aligned as well.
  78 .Pp
  79 The
  80 .Fn calloc
  81 function allocates space for
  82 .Fa number
  83 objects,
  84 each
  85 .Fa size
  86 bytes in length.
  87 The result is identical to calling
  88 .Fn malloc
  89 with an argument of
  90 .Dq "number * size" ,
  91 with the exception that the allocated memory is explicitly initialized
  92 to zero bytes.
  93 .Pp
  94 The
  95 .Fn realloc
  96 function changes the size of the previously allocated memory referenced by
  97 .Fa ptr
  98 to
  99 .Fa size
 100 bytes.
 101 The contents of the memory are unchanged up to the lesser of the new and
 102 old sizes.
 103 If the new size is larger,
 104 the value of the newly allocated portion of the memory is undefined.
 105 Upon success, the memory referenced by
 106 .Fa ptr
 107 is freed and a pointer to the newly allocated memory is returned.
 108 Note that
 109 .Fn realloc
 110 may move the memory allocation, resulting in a different return value than
 111 .Fa ptr .
 112 If
 113 .Fa ptr
 114 is
 115 .Dv NULL ,
 116 the
 117 .Fn realloc
 118 function behaves identically to
 119 .Fn malloc
 120 for the specified size.
 121 .Pp
 122 The
 123 .Fn reallocf
 124 function call is identical to the realloc function call, except that it
 125 will free the passed pointer when the requested memory cannot be allocated.
 126 This is a
 127 .Fx
 128 /
 129 .Dx
 130 specific API designed to ease the problems with traditional coding styles
 131 for realloc causing memory leaks in libraries.
 132 .Pp
 133 The
 134 .Fn free
 135 function causes the allocated memory referenced by
 136 .Fa ptr
 137 to be made available for future allocations.
 138 If
 139 .Fa ptr
 140 is
 141 .Dv NULL ,
 142 no action occurs.
 143 .Sh IMPLEMENTATION NOTES
 144 .Dx Ap s
 145 .Nm
 146 implementation is based on a port of the
 147 .Dx
 148 kernel slab allocator, appropriately modified for a user process
 149 environment.
 150 .Pp
 151 The slab allocator breaks memory allocations up to 8KB into 80 zones.
 152 Each zone represents a fixed allocation size in multiples of some
 153 core chunking.
 154 The chunking is a power-of-2 but the fixed allocation size is not.
 155 For example, a 1025-byte request is allocated out of the zone with a
 156 chunking of 128, thus in multiples of 1152 bytes.
 157 The minimum chunking, used for allocations in the 0-127 byte range,
 158 is 8 bytes (16 of the 80 zones).
 159 Beyond that the power-of-2 chunking is between 1/8 and 1/16 of the
 160 minimum allocation size for any given zone.
 161 .Pp
 162 As a special case any power-of-2-sized allocation within the zone
 163 limit (8K) will be aligned to the same power-of-2 rather than that
 164 zone's (smaller) chunking.
 165 This is not something you can depend upon for
 166 .Fn malloc ,
 167 but it is used internally to optimize
 168 .Xr posix_memalign 3 .
 169 .Pp
 170 Each zone reserves memory in 64KB blocks.
 171 Actual memory use tends to be significantly less as only the pages
 172 actually needed are faulted in.
 173 Allocations larger than 8K are managed using
 174 .Xr mmap 2
 175 and tracked with a hash table.
 176 .Pp
 177 The zone mechanism results in well-fitted allocations with little
 178 waste in a long-running environment which makes a lot of allocations.
 179 Short-running environments which do not make many allocations will see
 180 a bit of extra bloat due to the large number of zones but it will
 181 be almost unnoticeable in the grand scheme of things.
 182 To reduce bloat further the normal randomized start offset implemented
 183 in the kernel version of the allocator to improve L1 cache fill is
 184 disabled in the libc version.
 185 .Pp
 186 The zone mechanism also has the nice side effect of greatly reducing
 187 fragmentation over the original
 188 .Nm .
 189 .Pp
 190 .Fn calloc
 191 is directly supported by keeping track of newly-allocated zones which
 192 will be demand-zero'd by the system.
 193 If the allocation is known to be zero'd we do not bother
 194 .Fn bzero Ns ing
 195 it.
 196 If it is a reused allocation we
 197 .Fn bzero .
 198 .Pp
 199 .Tn POSIX
 200 threading is supported by duplicating the primary structure.
 201 A thread entering
 202 .Fn malloc
 203 which is unable to immediately acquire a mutex on the last primary
 204 structure it used will switch to a different primary structure.
 205 At the moment this is more of a quick hack than a solution, but it works.
 206 .Sh RETURN VALUES
 207 The
 208 .Fn malloc
 209 and
 210 .Fn calloc
 211 functions return a pointer to the allocated memory if successful; otherwise
 212 a
 213 .Dv NULL
 214 pointer is returned and
 215 .Va errno
 216 is set to
 217 .Er ENOMEM .
 218 .Pp
 219 The
 220 .Fn realloc
 221 and
 222 .Fn reallocf
 223 functions return a pointer, possibly identical to
 224 .Fa ptr ,
 225 to the allocated memory
 226 if successful; otherwise a
 227 .Dv NULL
 228 pointer is returned, and
 229 .Va errno
 230 is set to
 231 .Er ENOMEM
 232 if the error was the result of an allocation failure.
 233 The
 234 .Fn realloc
 235 function always leaves the original buffer intact
 236 when an error occurs, whereas
 237 .Fn reallocf
 238 deallocates it in this case.
 239 .Pp
 240 The
 241 .Fn free
 242 function returns no value.
 243 .Sh EXAMPLES
 244 When using
 245 .Fn malloc ,
 246 be careful to avoid the following idiom:
 247 .Bd -literal -offset indent
 248 if ((p = malloc(number * size)) == NULL)
 249         err(EXIT_FAILURE, "malloc");
 250 .Ed
 251 .Pp
 252 The multiplication may lead to an integer overflow.
 253 To avoid this,
 254 .Fn calloc
 255 is recommended.
 256 .Pp
 257 If
 258 .Fn malloc
 259 must be used, be sure to test for overflow:
 260 .Bd -literal -offset indent
 261 if (size && number > SIZE_MAX / size) {
 262         errno = EOVERFLOW;
 263         err(EXIT_FAILURE, "allocation");
 264 }
 265 .Ed
 266 .Pp
 267 When using
 268 .Fn realloc ,
 269 one must be careful to avoid the following idiom:
 270 .Bd -literal -offset indent
 271 nsize += 50;
 272
 273 if ((p = realloc(p, nsize)) == NULL)
 274         return NULL;
 275 .Ed
 276 .Pp
 277 Do not adjust the variable describing how much memory has been allocated
 278 until it is known that the allocation has been successful.
 279 This can cause aberrant program behavior if the incorrect size value is used.
 280 In most cases, the above example will also leak memory.
 281 As stated earlier, a return value of
 282 .Dv NULL
 283 indicates that the old object still remains allocated.
 284 Better code looks like this:
 285 .Bd -literal -offset indent
 286 newsize = size + 50;
 287
 288 if ((p2 = realloc(p, newsize)) == NULL) {
 289
 290         if (p != NULL)
 291                 free(p);
 292
 293         p = NULL;
 294         return NULL;
 295 }
 296
 297 p = p2;
 298 size = newsize;
 299 .Ed
 300 .Sh DIAGNOSTICS
 301 If
 302 .Fn malloc ,
 303 .Fn calloc ,
 304 .Fn realloc
 305 or
 306 .Fn free
 307 detect an error, a message will be printed to file descriptor
 308 .Dv STDERR_FILENO
 309 and the process will dump core.
 310 .Sh SEE ALSO
 311 .Xr madvise 2 ,
 312 .Xr mmap 2 ,
 313 .Xr sbrk 2 ,
 314 .Xr alloca 3 ,
 315 .Xr atexit 3 ,
 316 .Xr emalloc 3 ,
 317 .Xr getpagesize 3 ,
 318 .Xr memory 3 ,
 319 .Xr posix_memalign 3
 320 .Sh STANDARDS
 321 The
 322 .Fn malloc ,
 323 .Fn calloc ,
 324 .Fn realloc
 325 and
 326 .Fn free
 327 functions conform to
 328 .St -isoC .
 329 .Sh HISTORY
 330 The
 331 .Fn reallocf
 332 function first appeared in
 333 .Fx 3.0 .
 334 .Pp
 335 .Dx Ap s
 336 .Nm
 337 implementation is based on the kernel's slab allocator (see
 338 .Xr posix_memalign 3 Ap s
 339 .Sx IMPLEMENTATION NOTES ) .
 340 It first appeared in
 341 .Dx 2.3 .
 342 .Sh AUTHORS
 343 .An Matt Dillon