lib/libc/stdlib/malloc.3

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)malloc.3    8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.25.2.16 2003/01/06 17:10:45 trhodes Exp $
  38 .\" $DragonFly: src/lib/libc/stdlib/malloc.3,v 1.8 2008/05/02 02:05:04 swildner Exp $
  39 .\"
  40 .Dd May 2, 2009
  41 .Dt MALLOC 3
  42 .Os
  43 .Sh NAME
  44 .Nm malloc ,
  45 .Nm calloc ,
  46 .Nm realloc ,
  47 .Nm free ,
  48 .Nm reallocf
  49 .Nd general purpose memory allocation functions
  50 .Sh LIBRARY
  51 .Lb libc
  52 .Sh SYNOPSIS
  53 .In stdlib.h
  54 .Ft void *
  55 .Fn malloc "size_t size"
  56 .Ft void *
  57 .Fn calloc "size_t number" "size_t size"
  58 .Ft void *
  59 .Fn realloc "void *ptr" "size_t size"
  60 .Ft void *
  61 .Fn reallocf "void *ptr" "size_t size"
  62 .Ft void
  63 .Fn free "void *ptr"
  64 .Sh DESCRIPTION
  65 The
  66 .Fn malloc
  67 function allocates
  68 .Fa size
  69 bytes of memory.
  70 The allocated space is suitably aligned (after possible pointer coercion)
  71 for storage of any type of object.
  72 If the space is at least
  73 .Em pagesize
  74 bytes in length (see
  75 .Xr getpagesize 3 ) ,
  76 the returned memory will be page boundary aligned as well.
  77 If
  78 .Fn malloc
  79 fails, a
  80 .Dv NULL
  81 pointer is returned.
  82 .Pp
  83 Note that
  84 .Fn malloc
  85 does
  86 .Em NOT
  87 normally initialize the returned memory to zero bytes.
  88 .Pp
  89 The
  90 .Fn calloc
  91 function allocates space for
  92 .Fa number
  93 objects,
  94 each
  95 .Fa size
  96 bytes in length.
  97 The result is identical to calling
  98 .Fn malloc
  99 with an argument of
 100 .Dq Fa number * Fa size ,
 101 with the exception that the allocated memory is explicitly initialized
 102 to zero bytes.
 103 .Pp
 104 The
 105 .Fn realloc
 106 function changes the size of the previously allocated memory referenced by
 107 .Fa ptr
 108 to
 109 .Fa size
 110 bytes.
 111 The contents of the memory are unchanged up to the lesser of the new and
 112 old sizes.
 113 If the new size is larger,
 114 the value of the newly allocated portion of the memory is undefined.
 115 If the requested memory cannot be allocated,
 116 .Dv NULL
 117 is returned and
 118 the memory referenced by
 119 .Fa ptr
 120 is valid and unchanged.
 121 If
 122 .Fa ptr
 123 is
 124 .Dv NULL ,
 125 the
 126 .Fn realloc
 127 function behaves identically to
 128 .Fn malloc
 129 for the specified size.
 130 .Pp
 131 The
 132 .Fn reallocf
 133 function call is identical to the realloc function call, except that it
 134 will free the passed pointer when the requested memory cannot be allocated.
 135 This is a
 136 .Fx
 137 /
 138 .Dx
 139 specific API designed to ease the problems with traditional coding styles
 140 for realloc causing memory leaks in libraries.
 141 .Pp
 142 The
 143 .Fn free
 144 function causes the allocated memory referenced by
 145 .Fa ptr
 146 to be made available for future allocations.
 147 If
 148 .Fa ptr
 149 is
 150 .Dv NULL ,
 151 no action occurs.
 152 .Sh IMPLEMENTATION NOTES
 153 .Dx Ap s
 154 .Nm
 155 implementation is based on a port of the
 156 .Dx
 157 kernel slab allocator, appropriately modified for a user process
 158 environment.
 159 .Pp
 160 The slab allocator breaks memory allocations up to 8KB into 80 zones.
 161 Each zone represents a fixed allocation size in multiples of some
 162 core chunking.
 163 The chunking is a power-of-2 but the fixed allocation size is not.
 164 For example, a 1025-byte request is allocated out of the zone with a
 165 chunking of 128, thus in multiples of 1152 bytes.
 166 The minimum chunking, used for allocations in the 0-127 byte range,
 167 is 8 bytes (16 of the 80 zones).
 168 Beyond that the power-of-2 chunking is between 1/8 and 1/16 of the
 169 minimum allocation size for any given zone.
 170 .Pp
 171 As a special case any power-of-2-sized allocation within the zone
 172 limit (8K) will be aligned to the same power-of-2 rather than that
 173 zone's (smaller) chunking.
 174 This is not something you can depend upon for
 175 .Fn malloc ,
 176 but it is used internally to optimize
 177 .Xr posix_memalign 3 .
 178 .Pp
 179 Each zone reserves memory in 64KB blocks.
 180 Actual memory use tends to be significantly less as only the pages
 181 actually needed are faulted in.
 182 Allocations larger than 8K are managed using
 183 .Xr mmap 2
 184 and tracked with a hash table.
 185 .Pp
 186 The zone mechanism results in well-fitted allocations with little
 187 waste in a long-running environment which makes a lot of allocations.
 188 Short-running environments which do not make many allocations will see
 189 a bit of extra bloat due to the large number of zones but it will
 190 be almost unnoticeable in the grand scheme of things.
 191 To reduce bloat further the normal randomized start offset implemented
 192 in the kernel version of the allocator to improve L1 cache fill is
 193 disabled in the libc version.
 194 .Pp
 195 The zone mechanism also has the nice side effect of greatly reducing
 196 fragmentation over the original
 197 .Nm .
 198 .Pp
 199 .Fn calloc
 200 is directly supported by keeping track of newly-allocated zones which
 201 will be demand-zero'd by the system.
 202 If the allocation is known to be zero'd we do not bother
 203 .Fn bzero Ns ing
 204 it.
 205 If it is a reused allocation we
 206 .Fn bzero .
 207 .Pp
 208 .Tn POSIX
 209 threading is supported by duplicating the primary structure.
 210 A thread entering
 211 .Fn malloc
 212 which is unable to immediately acquire a mutex on the last primary
 213 structure it used will switch to a different primary structure.
 214 At the moment this is more of a quick hack than a solution, but it works.
 215 .Sh RETURN VALUES
 216 The
 217 .Fn malloc
 218 and
 219 .Fn calloc
 220 functions return a pointer to the allocated memory if successful; otherwise
 221 a
 222 .Dv NULL
 223 pointer is returned and
 224 .Va errno
 225 is set to
 226 .Er ENOMEM .
 227 .Pp
 228 The
 229 .Fn realloc
 230 and
 231 .Fn reallocf
 232 functions return a pointer, possibly identical to
 233 .Fa ptr ,
 234 to the allocated memory
 235 if successful; otherwise a
 236 .Dv NULL
 237 pointer is returned, and
 238 .Va errno
 239 is set to
 240 .Er ENOMEM
 241 if the error was the result of an allocation failure.
 242 The
 243 .Fn realloc
 244 function always leaves the original buffer intact
 245 when an error occurs, whereas
 246 .Fn reallocf
 247 deallocates it in this case.
 248 .Pp
 249 The
 250 .Fn free
 251 function returns no value.
 252 .Sh DIAGNOSTIC MESSAGES
 253 If
 254 .Fn malloc ,
 255 .Fn calloc ,
 256 .Fn realloc
 257 or
 258 .Fn free
 259 detect an error, a message will be printed to file descriptor
 260 .Dv STDERR_FILENO
 261 and the process will dump core.
 262 .Sh SEE ALSO
 263 .Xr brk 2 ,
 264 .Xr mmap 2 ,
 265 .Xr alloca 3 ,
 266 .Xr getpagesize 3 ,
 267 .Xr memory 3 ,
 268 .Xr posix_memalign 3
 269 .Sh STANDARDS
 270 The
 271 .Fn malloc ,
 272 .Fn calloc ,
 273 .Fn realloc
 274 and
 275 .Fn free
 276 functions conform to
 277 .St -isoC .
 278 .Sh HISTORY
 279 The
 280 .Fn reallocf
 281 function first appeared in
 282 .Fx 3.0 .
 283 .Pp
 284 .Dx Ap s
 285 .Nm
 286 implementation is based on the kernel's slab allocator (see
 287 .Xr posix_memalign 3 Ap s
 288 .Sx IMPLEMENTATION NOTES ) .
 289 It first appeared in
 290 .Dx 2.3 .
 291 .Sh AUTHORS
 292 .An Matt Dillon