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