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. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)malloc.3    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd April 4, 2006
  36 .Dt MALLOC 3
  37 .Os
  38 .Sh NAME
  39 .Nm malloc , calloc , realloc , free , reallocf , malloc_usable_size
  40 .Nd general purpose memory allocation functions
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In stdlib.h
  45 .Ft void *
  46 .Fn malloc "size_t size"
  47 .Ft void *
  48 .Fn calloc "size_t number" "size_t size"
  49 .Ft void *
  50 .Fn realloc "void *ptr" "size_t size"
  51 .Ft void *
  52 .Fn reallocf "void *ptr" "size_t size"
  53 .Ft void
  54 .Fn free "void *ptr"
  55 .Ft const char *
  56 .Va _malloc_options ;
  57 .Ft void
  58 .Fo \*(lp*_malloc_message\*(rp
  59 .Fa "const char *p1" "const char *p2" "const char *p3" "const char *p4"
  60 .Fc
  61 .In malloc_np.h
  62 .Ft size_t
  63 .Fn malloc_usable_size "const void *ptr"
  64 .Sh DESCRIPTION
  65 The
  66 .Fn malloc
  67 function allocates
  68 .Fa size
  69 bytes of uninitialized memory.
  70 The allocated space is suitably aligned (after possible pointer coercion)
  71 for storage of any type of object.
  72 .Pp
  73 The
  74 .Fn calloc
  75 function allocates space for
  76 .Fa number
  77 objects,
  78 each
  79 .Fa size
  80 bytes in length.
  81 The result is identical to calling
  82 .Fn malloc
  83 with an argument of
  84 .Dq "number * size" ,
  85 with the exception that the allocated memory is explicitly initialized
  86 to zero bytes.
  87 .Pp
  88 The
  89 .Fn realloc
  90 function changes the size of the previously allocated memory referenced by
  91 .Fa ptr
  92 to
  93 .Fa size
  94 bytes.
  95 The contents of the memory are unchanged up to the lesser of the new and
  96 old sizes.
  97 If the new size is larger,
  98 the value of the newly allocated portion of the memory is undefined.
  99 Upon success, the memory referenced by
 100 .Fa ptr
 101 is freed and a pointer to the newly allocated memory is returned.
 102 Note that
 103 .Fn realloc
 104 and
 105 .Fn reallocf
 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 is identical to the
 121 .Fn realloc
 122 function, except that it
 123 will free the passed pointer when the requested memory cannot be allocated.
 124 This is a
 125 .Fx
 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 .Pp
 140 The
 141 .Fn malloc_usable_size
 142 function returns the usable size of the allocation pointed to by
 143 .Fa ptr .
 144 The return value may be larger than the size that was requested during
 145 allocation.
 146 The
 147 .Fn malloc_usable_size
 148 function is not a mechanism for in-place
 149 .Fn realloc ;
 150 rather it is provided solely as a tool for introspection purposes.
 151 Any discrepancy between the requested allocation size and the size reported by
 152 .Fn malloc_usable_size
 153 should not be depended on, since such behavior is entirely
 154 implementation-dependent.
 155 .Sh TUNING
 156 Once, when the first call is made to one of these memory allocation
 157 routines, various flags will be set or reset, which affect the
 158 workings of this allocator implementation.
 159 .Pp
 160 The
 161 .Dq name
 162 of the file referenced by the symbolic link named
 163 .Pa /etc/malloc.conf ,
 164 the value of the environment variable
 165 .Ev MALLOC_OPTIONS ,
 166 and the string pointed to by the global variable
 167 .Va _malloc_options
 168 will be interpreted, in that order, character by character as flags.
 169 .Pp
 170 Most flags are single letters,
 171 where uppercase indicates that the behavior is set, or on,
 172 and lowercase means that the behavior is not set, or off.
 173 .Bl -tag -width indent
 174 .It A
 175 All warnings (except for the warning about unknown
 176 flags being set) become fatal.
 177 The process will call
 178 .Xr abort 3
 179 in these cases.
 180 .It H
 181 Use
 182 .Xr madvise 2
 183 when pages within a chunk are no longer in use, but the chunk as a whole cannot
 184 yet be deallocated.
 185 This is primarily of use when swapping is a real possibility, due to the high
 186 overhead of the
 187 .Fn madvise
 188 system call.
 189 .It J
 190 Each byte of new memory allocated by
 191 .Fn malloc ,
 192 .Fn realloc
 193 or
 194 .Fn reallocf
 195 will be initialized to 0xa5.
 196 All memory returned by
 197 .Fn free ,
 198 .Fn realloc
 199 or
 200 .Fn reallocf
 201 will be initialized to 0x5a.
 202 This is intended for debugging and will impact performance negatively.
 203 .It K
 204 Increase/decrease the virtual memory chunk size by a factor of two.
 205 The default chunk size is 2 MB.
 206 This option can be specified multiple times.
 207 .It N
 208 Increase/decrease the number of arenas by a factor of two.
 209 The default number of arenas is four times the number of CPUs, or one if there
 210 is a single CPU.
 211 This option can be specified multiple times.
 212 .It P
 213 Various statistics are printed at program exit via an
 214 .Xr atexit 3
 215 function.
 216 This has the potential to cause deadlock for a multi-threaded process that exits
 217 while one or more threads are executing in the memory allocation functions.
 218 Therefore, this option should only be used with care; it is primarily intended
 219 as a performance tuning aid during application development.
 220 .It Q
 221 Increase/decrease the size of the allocation quantum by a factor of two.
 222 The default quantum is the minimum allowed by the architecture (typically 8 or
 223 16 bytes).
 224 This option can be specified multiple times.
 225 .It S
 226 Increase/decrease the size of the maximum size class that is a multiple of the
 227 quantum by a factor of two.
 228 Above this size, power-of-two spacing is used for size classes.
 229 The default value is 512 bytes.
 230 This option can be specified multiple times.
 231 .It U
 232 Generate
 233 .Dq utrace
 234 entries for
 235 .Xr ktrace 1 ,
 236 for all operations.
 237 Consult the source for details on this option.
 238 .It V
 239 Attempting to allocate zero bytes will return a
 240 .Dv NULL
 241 pointer instead of
 242 a valid pointer.
 243 (The default behavior is to make a minimal allocation and return a
 244 pointer to it.)
 245 This option is provided for System V compatibility.
 246 This option is incompatible with the
 247 .Dq X
 248 option.
 249 .It X
 250 Rather than return failure for any allocation function,
 251 display a diagnostic message on
 252 .Dv stderr
 253 and cause the program to drop
 254 core (using
 255 .Xr abort 3 ) .
 256 This option should be set at compile time by including the following in
 257 the source code:
 258 .Bd -literal -offset indent
 259 _malloc_options = "X";
 260 .Ed
 261 .It Z
 262 Each byte of new memory allocated by
 263 .Fn malloc ,
 264 .Fn realloc
 265 or
 266 .Fn reallocf
 267 will be initialized to 0.
 268 Note that this initialization only happens once for each byte, so
 269 .Fn realloc
 270 and
 271 .Fn reallocf
 272 calls do not zero memory that was previously allocated.
 273 This is intended for debugging and will impact performance negatively.
 274 .El
 275 .Pp
 276 The
 277 .Dq J
 278 and
 279 .Dq Z
 280 options are intended for testing and debugging.
 281 An application which changes its behavior when these options are used
 282 is flawed.
 283 .Sh IMPLEMENTATION NOTES
 284 This allocator uses multiple arenas in order to reduce lock contention for
 285 threaded programs on multi-processor systems.
 286 This works well with regard to threading scalability, but incurs some costs.
 287 There is a small fixed per-arena overhead, and additionally, arenas manage
 288 memory completely independently of each other, which means a small fixed
 289 increase in overall memory fragmentation.
 290 These overheads are not generally an issue, given the number of arenas normally
 291 used.
 292 Note that using substantially more arenas than the default is not likely to
 293 improve performance, mainly due to reduced cache performance.
 294 However, it may make sense to reduce the number of arenas if an application
 295 does not make much use of the allocation functions.
 296 .Pp
 297 Chunks manage their pages by using a power-of-two buddy allocation strategy.
 298 Each chunk maintains a page map that makes it possible to determine the state
 299 of any page in the chunk in constant time.
 300 Allocations that are no larger than one half of a page are managed in groups by
 301 page
 302 .Dq runs .
 303 Each run maintains a bitmap that tracks which regions are in use.
 304 Allocation requests that are no more than half the quantum (see the
 305 .Dq Q
 306 option) are rounded up to the nearest power of two (typically 2, 4, or 8).
 307 Allocation requests that are more than half the quantum, but no more than the
 308 maximum quantum-multiple size class (see the
 309 .Dq S
 310 option) are rounded up to the nearest multiple of the quantum.
 311 Allocation requests that are larger than the maximum quantum-multiple size
 312 class, but no larger than one half of a page, are rounded up to the nearest
 313 power of two.
 314 Allocation requests that are larger than half of a page, but no larger than half
 315 of a chunk (see the
 316 .Dq K
 317 option), are rounded up to the nearest run size.
 318 Allocation requests that are larger than half of a chunk are rounded up to the
 319 nearest multiple of the chunk size.
 320 .Pp
 321 Allocations are packed tightly together, which can be an issue for
 322 multi-threaded applications.
 323 If you need to assure that allocations do not suffer from cache line sharing,
 324 round your allocation requests up to the nearest multiple of the cache line
 325 size.
 326 .Sh DEBUGGING MALLOC PROBLEMS
 327 The first thing to do is to set the
 328 .Dq A
 329 option.
 330 This option forces a coredump (if possible) at the first sign of trouble,
 331 rather than the normal policy of trying to continue if at all possible.
 332 .Pp
 333 It is probably also a good idea to recompile the program with suitable
 334 options and symbols for debugger support.
 335 .Pp
 336 If the program starts to give unusual results, coredump or generally behave
 337 differently without emitting any of the messages mentioned in the next
 338 section, it is likely because it depends on the storage being filled with
 339 zero bytes.
 340 Try running it with the
 341 .Dq Z
 342 option set;
 343 if that improves the situation, this diagnosis has been confirmed.
 344 If the program still misbehaves,
 345 the likely problem is accessing memory outside the allocated area.
 346 .Pp
 347 Alternatively, if the symptoms are not easy to reproduce, setting the
 348 .Dq J
 349 option may help provoke the problem.
 350 .Pp
 351 In truly difficult cases, the
 352 .Dq U
 353 option, if supported by the kernel, can provide a detailed trace of
 354 all calls made to these functions.
 355 .Pp
 356 Unfortunately this implementation does not provide much detail about
 357 the problems it detects; the performance impact for storing such information
 358 would be prohibitive.
 359 There are a number of allocation implementations available on the Internet
 360 which focus on detecting and pinpointing problems by trading performance for
 361 extra sanity checks and detailed diagnostics.
 362 .Sh DIAGNOSTIC MESSAGES
 363 If any of the memory allocation/deallocation functions detect an error or
 364 warning condition, a message will be printed to file descriptor
 365 .Dv STDERR_FILENO .
 366 Errors will result in the process dumping core.
 367 If the
 368 .Dq A
 369 option is set, all warnings are treated as errors.
 370 .Pp
 371 The
 372 .Va _malloc_message
 373 variable allows the programmer to override the function which emits
 374 the text strings forming the errors and warnings if for some reason
 375 the
 376 .Dv stderr
 377 file descriptor is not suitable for this.
 378 Please note that doing anything which tries to allocate memory in
 379 this function is likely to result in a crash or deadlock.
 380 .Pp
 381 All messages are prefixed by
 382 .Dq Ao Ar progname Ac Ns Li : (malloc) .
 383 .Sh RETURN VALUES
 384 The
 385 .Fn malloc
 386 and
 387 .Fn calloc
 388 functions return a pointer to the allocated memory if successful; otherwise
 389 a
 390 .Dv NULL
 391 pointer is returned and
 392 .Va errno
 393 is set to
 394 .Er ENOMEM .
 395 .Pp
 396 The
 397 .Fn realloc
 398 and
 399 .Fn reallocf
 400 functions return a pointer, possibly identical to
 401 .Fa ptr ,
 402 to the allocated memory
 403 if successful; otherwise a
 404 .Dv NULL
 405 pointer is returned, and
 406 .Va errno
 407 is set to
 408 .Er ENOMEM
 409 if the error was the result of an allocation failure.
 410 The
 411 .Fn realloc
 412 function always leaves the original buffer intact
 413 when an error occurs, whereas
 414 .Fn reallocf
 415 deallocates it in this case.
 416 .Pp
 417 The
 418 .Fn free
 419 function returns no value.
 420 .Pp
 421 The
 422 .Fn malloc_usable_size
 423 function returns the usable size of the allocation pointed to by
 424 .Fa ptr .
 425 .Sh ENVIRONMENT
 426 The following environment variables affect the execution of the allocation
 427 functions:
 428 .Bl -tag -width ".Ev MALLOC_OPTIONS"
 429 .It Ev MALLOC_OPTIONS
 430 If the environment variable
 431 .Ev MALLOC_OPTIONS
 432 is set, the characters it contains will be interpreted as flags to the
 433 allocation functions.
 434 .El
 435 .Sh EXAMPLES
 436 To dump core whenever a problem occurs:
 437 .Pp
 438 .Bd -literal -offset indent
 439 ln -s 'A' /etc/malloc.conf
 440 .Ed
 441 .Pp
 442 To specify in the source that a program does no return value checking
 443 on calls to these functions:
 444 .Bd -literal -offset indent
 445 _malloc_options = "X";
 446 .Ed
 447 .Sh SEE ALSO
 448 .Xr madvise 2 ,
 449 .Xr mmap 2 ,
 450 .Xr alloca 3 ,
 451 .Xr atexit 3 ,
 452 .Xr getpagesize 3 ,
 453 .Xr memory 3 ,
 454 .Xr posix_memalign 3
 455 .Sh STANDARDS
 456 The
 457 .Fn malloc ,
 458 .Fn calloc ,
 459 .Fn realloc
 460 and
 461 .Fn free
 462 functions conform to
 463 .St -isoC .
 464 .Sh HISTORY
 465 The
 466 .Fn reallocf
 467 function first appeared in
 468 .Fx 3.0 .
 469 .Pp
 470 The
 471 .Fn malloc_usable_size
 472 function first appeared in
 473 .Fx 7.0 .