6/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$
  38 .\"
  39 .Dd June 21, 2006
  40 .Dt MALLOC 3
  41 .Os
  42 .Sh NAME
  43 .Nm malloc , calloc , realloc , free , reallocf
  44 .Nd general purpose memory allocation functions
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In stdlib.h
  49 .Ft void *
  50 .Fn malloc "size_t size"
  51 .Ft void *
  52 .Fn calloc "size_t number" "size_t size"
  53 .Ft void *
  54 .Fn realloc "void *ptr" "size_t size"
  55 .Ft void *
  56 .Fn reallocf "void *ptr" "size_t size"
  57 .Ft void
  58 .Fn free "void *ptr"
  59 .Ft const char *
  60 .Va _malloc_options ;
  61 .Ft void
  62 .Fn \*(lp*_malloc_message\*(rp "char *p1" "char *p2" "char *p3" "char *p4"
  63 .Sh DESCRIPTION
  64 The
  65 .Fn malloc
  66 function allocates
  67 .Fa size
  68 bytes of memory.
  69 The allocated space is suitably aligned (after possible pointer coercion)
  70 for storage of any type of object.
  71 If the space is at least
  72 .Va pagesize
  73 bytes in length (see
  74 .Xr getpagesize 3 ) ,
  75 the returned memory will be page boundary aligned as well.
  76 If
  77 .Fn malloc
  78 fails, a
  79 .Dv NULL
  80 pointer is returned.
  81 .Pp
  82 Note that
  83 .Fn malloc
  84 does
  85 .Em NOT
  86 normally initialize the returned memory to zero bytes.
  87 .Pp
  88 The
  89 .Fn calloc
  90 function allocates space for
  91 .Fa number
  92 objects,
  93 each
  94 .Fa size
  95 bytes in length.
  96 The result is identical to calling
  97 .Fn malloc
  98 with an argument of
  99 .Dq "number * size" ,
 100 with the exception that the allocated memory is explicitly initialized
 101 to zero bytes.
 102 .Pp
 103 The
 104 .Fn realloc
 105 function changes the size of the previously allocated memory referenced by
 106 .Fa ptr
 107 to
 108 .Fa size
 109 bytes.
 110 The contents of the memory are unchanged up to the lesser of the new and
 111 old sizes.
 112 If the new size is larger,
 113 the value of the newly allocated portion of the memory is undefined.
 114 If the requested memory cannot be allocated,
 115 .Dv NULL
 116 is returned and
 117 the memory referenced by
 118 .Fa ptr
 119 is valid and unchanged.
 120 If memory can be allocated, the memory referenced by
 121 .Fa ptr
 122 is freed and a pointer to the newly allocated memory is returned.
 123 Note that
 124 .Fn realloc
 125 and
 126 .Fn reallocf
 127 may move the memory allocation resulting in a different return value than
 128 .Fa ptr .
 129 If
 130 .Fa ptr
 131 is
 132 .Dv NULL ,
 133 the
 134 .Fn realloc
 135 function behaves identically to
 136 .Fn malloc
 137 for the specified size.
 138 .Pp
 139 The
 140 .Fn reallocf
 141 function is identical to the
 142 .Fn realloc
 143 function, except that it
 144 will free the passed pointer when the requested memory cannot be allocated.
 145 This is a
 146 .Fx
 147 specific API designed to ease the problems with traditional coding styles
 148 for realloc causing memory leaks in libraries.
 149 .Pp
 150 The
 151 .Fn free
 152 function causes the allocated memory referenced by
 153 .Fa ptr
 154 to be made available for future allocations.
 155 If
 156 .Fa ptr
 157 is
 158 .Dv NULL ,
 159 no action occurs.
 160 .Sh TUNING
 161 Once, when the first call is made to one of these memory allocation
 162 routines, various flags will be set or reset, which affect the
 163 workings of this allocation implementation.
 164 .Pp
 165 The ``name'' of the file referenced by the symbolic link named
 166 .Pa /etc/malloc.conf ,
 167 the value of the environment variable
 168 .Ev MALLOC_OPTIONS ,
 169 and the string pointed to by the global variable
 170 .Va _malloc_options
 171 will be interpreted, in that order, character by character as flags.
 172 .Pp
 173 Most flags are single letters,
 174 where uppercase indicates that the behavior is set, or on,
 175 and lowercase means that the behavior is not set, or off.
 176 .Bl -tag -width indent
 177 .It A
 178 All warnings (except for the warning about unknown
 179 flags being set) become fatal.
 180 The process will call
 181 .Xr abort 3
 182 in these cases.
 183 .It J
 184 Each byte of new memory allocated by
 185 .Fn malloc ,
 186 .Fn realloc
 187 or
 188 .Fn reallocf
 189 as well as all memory returned by
 190 .Fn free ,
 191 .Fn realloc
 192 or
 193 .Fn reallocf
 194 will be initialized to 0xd0.
 195 This is intended for debugging and will impact performance negatively.
 196 .It H
 197 Pass a hint to the kernel about pages unused by the allocation functions.
 198 This will help performance if the system is paging excessively.
 199 This option is off by default.
 200 .It R
 201 Causes the
 202 .Fn realloc
 203 and
 204 .Fn reallocf
 205 functions to always reallocate memory even if the initial allocation was
 206 sufficiently large.
 207 This can substantially aid in compacting memory.
 208 .It U
 209 Generate
 210 .Dq utrace
 211 entries for
 212 .Xr ktrace 1 ,
 213 for all operations.
 214 Consult the source for details on this option.
 215 .It V
 216 Attempting to allocate zero bytes will return a
 217 .Dv NULL
 218 pointer instead of
 219 a valid pointer.
 220 (The default behavior is to make a minimal allocation and return a
 221 pointer to it.)
 222 This option is provided for System V compatibility.
 223 This option is incompatible with the
 224 .Dq X
 225 option.
 226 .It X
 227 Rather than return failure for any allocation function,
 228 display a diagnostic message on
 229 .Dv stderr
 230 and cause the program to drop
 231 core (using
 232 .Xr abort 3 ) .
 233 This option should be set at compile time by including the following in
 234 the source code:
 235 .Bd -literal -offset indent
 236 _malloc_options = "X";
 237 .Ed
 238 .It Z
 239 This option implicitly sets the
 240 .Dq J
 241 option, and then zeros out the bytes that were requested.
 242 This is intended for debugging and will impact performance negatively.
 243 .It <
 244 Reduce the size of the cache by a factor of two.
 245 The default cache size is 16 pages.
 246 This option can be specified multiple times.
 247 .It >
 248 Double the size of the cache by a factor of two.
 249 The default cache size is 16 pages.
 250 This option can be specified multiple times.
 251 .El
 252 .Pp
 253 The
 254 .Dq J
 255 and
 256 .Dq Z
 257 options are intended for testing and debugging.
 258 An application which changes its behavior when these options are used
 259 is flawed.
 260 .Sh RETURN VALUES
 261 The
 262 .Fn malloc
 263 and
 264 .Fn calloc
 265 functions return a pointer to the allocated memory if successful; otherwise
 266 a
 267 .Dv NULL
 268 pointer is returned and
 269 .Va errno
 270 is set to
 271 .Er ENOMEM .
 272 .Pp
 273 The
 274 .Fn realloc
 275 and
 276 .Fn reallocf
 277 functions return a pointer, possibly identical to
 278 .Fa ptr ,
 279 to the allocated memory
 280 if successful; otherwise a
 281 .Dv NULL
 282 pointer is returned, and
 283 .Va errno
 284 is set to
 285 .Er ENOMEM
 286 if the error was the result of an allocation failure.
 287 The
 288 .Fn realloc
 289 function always leaves the original buffer intact
 290 when an error occurs, whereas
 291 .Fn reallocf
 292 deallocates it in this case.
 293 .Pp
 294 The
 295 .Fn free
 296 function returns no value.
 297 .Sh DEBUGGING MALLOC PROBLEMS
 298 The major difference between this implementation and other allocation
 299 implementations is that the free pages are not accessed unless allocated,
 300 and are aggressively returned to the kernel for reuse.
 301 .Bd -ragged -offset indent
 302 Most allocation implementations will store a data structure containing a
 303 linked list in the free chunks of memory,
 304 used to tie all the free memory together.
 305 That can be suboptimal,
 306 as every time the free-list is traversed,
 307 the otherwise unused, and likely paged out,
 308 pages are faulted into primary memory.
 309 On systems which are paging,
 310 this can result in a factor of five increase in the number of page-faults
 311 done by a process.
 312 .Ed
 313 .Pp
 314 A side effect of this architecture is that many minor transgressions on
 315 the interface which would traditionally not be detected are in fact
 316 detected.
 317 As a result, programs that have been running happily for
 318 years may suddenly start to complain loudly, when linked with this
 319 allocation implementation.
 320 .Pp
 321 The first and most important thing to do is to set the
 322 .Dq A
 323 option.
 324 This option forces a coredump (if possible) at the first sign of trouble,
 325 rather than the normal policy of trying to continue if at all possible.
 326 .Pp
 327 It is probably also a good idea to recompile the program with suitable
 328 options and symbols for debugger support.
 329 .Pp
 330 If the program starts to give unusual results, coredump or generally behave
 331 differently without emitting any of the messages listed in the next
 332 section, it is likely because it depends on the storage being filled with
 333 zero bytes.
 334 Try running it with
 335 .Dq Z
 336 option set;
 337 if that improves the situation, this diagnosis has been confirmed.
 338 If the program still misbehaves,
 339 the likely problem is accessing memory outside the allocated area,
 340 more likely after than before the allocated area.
 341 .Pp
 342 Alternatively, if the symptoms are not easy to reproduce, setting the
 343 .Dq J
 344 option may help provoke the problem.
 345 .Pp
 346 In truly difficult cases, the
 347 .Dq U
 348 option, if supported by the kernel, can provide a detailed trace of
 349 all calls made to these functions.
 350 .Pp
 351 Unfortunately this implementation does not provide much detail about
 352 the problems it detects, the performance impact for storing such information
 353 would be prohibitive.
 354 There are a number of allocation implementations available on the 'Net
 355 which focus on detecting and pinpointing problems by trading performance
 356 for extra sanity checks and detailed diagnostics.
 357 .Sh DIAGNOSTIC MESSAGES
 358 If
 359 .Fn malloc ,
 360 .Fn calloc ,
 361 .Fn realloc
 362 or
 363 .Fn free
 364 detect an error or warning condition,
 365 a message will be printed to file descriptor 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 will assure death of the process.
 380 .Pp
 381 The following is a brief description of possible error messages and
 382 their meanings:
 383 .Pp
 384 .Bl -diag
 385 .It "(ES): mumble mumble mumble"
 386 The allocation functions were compiled with
 387 .Dq EXTRA_SANITY
 388 defined, and an error was found during the additional error checking.
 389 Consult the source code for further information.
 390 .It "mmap(2) failed, check limits"
 391 This most likely means that the system is dangerously overloaded or that
 392 the process' limits are incorrectly specified.
 393 .It "freelist is destroyed"
 394 The internal free-list has been corrupted.
 395 .It "out of memory"
 396 The
 397 .Dq X
 398 option was specified and an allocation of memory failed.
 399 .El
 400 .Pp
 401 The following is a brief description of possible warning messages and
 402 their meanings:
 403 .Bl -diag
 404 .It "chunk/page is already free"
 405 The process attempted to
 406 .Fn free
 407 memory which had already been freed.
 408 .It "junk pointer, ..."
 409 A pointer specified to one of the allocation functions points outside the
 410 bounds of the memory of which they are aware.
 411 .It "malloc() has never been called"
 412 No memory has been allocated,
 413 yet something is being freed or
 414 realloc'ed.
 415 .It "modified (chunk-/page-) pointer"
 416 The pointer passed to
 417 .Fn free
 418 or
 419 .Fn realloc
 420 has been modified.
 421 .It "pointer to wrong page"
 422 The pointer that
 423 .Fn free ,
 424 .Fn realloc ,
 425 or
 426 .Fn reallocf
 427 is trying to free does not reference a possible page.
 428 .It "recursive call"
 429 A process has attempted to call an allocation function recursively.
 430 This is not permitted.
 431 In particular, signal handlers should not
 432 attempt to allocate memory.
 433 .It "unknown char in MALLOC_OPTIONS"
 434 An unknown option was specified.
 435 Even with the
 436 .Dq A
 437 option set, this warning is still only a warning.
 438 .El
 439 .Sh ENVIRONMENT
 440 The following environment variables affect the execution of the allocation
 441 functions:
 442 .Bl -tag -width ".Ev MALLOC_OPTIONS"
 443 .It Ev MALLOC_OPTIONS
 444 If the environment variable
 445 .Ev MALLOC_OPTIONS
 446 is set, the characters it contains will be interpreted as flags to the
 447 allocation functions.
 448 .El
 449 .Sh EXAMPLES
 450 To set a systemwide reduction of cache size, and to dump core whenever
 451 a problem occurs:
 452 .Pp
 453 .Bd -literal -offset indent
 454 ln -s 'A<' /etc/malloc.conf
 455 .Ed
 456 .Pp
 457 To specify in the source that a program does no return value checking
 458 on calls to these functions:
 459 .Bd -literal -offset indent
 460 _malloc_options = "X";
 461 .Ed
 462 .Sh SEE ALSO
 463 .Xr brk 2 ,
 464 .Xr mmap 2 ,
 465 .Xr alloca 3 ,
 466 .Xr getpagesize 3 ,
 467 .Xr memory 3
 468 .Pa /usr/share/doc/papers/malloc.ascii.gz
 469 .Sh STANDARDS
 470 The
 471 .Fn malloc ,
 472 .Fn calloc ,
 473 .Fn realloc
 474 and
 475 .Fn free
 476 functions conform to
 477 .St -isoC .
 478 .Sh HISTORY
 479 The present allocation implementation started out as a file system for a
 480 drum attached to a 20bit binary challenged computer which was built
 481 with discrete germanium transistors.
 482 It has since graduated to
 483 handle primary storage rather than secondary.
 484 It first appeared in its new shape and ability in
 485 .Fx 2.2 .
 486 .Pp
 487 The
 488 .Fn reallocf
 489 function first appeared in
 490 .Fx 3.0 .
 491 .Sh AUTHORS
 492 .An Poul-Henning Kamp Aq phk@FreeBSD.org
 493 .Sh BUGS
 494 The messages printed in case of problems provide no detail about the
 495 actual values.
 496 .Pp
 497 It can be argued that returning a
 498 .Dv NULL
 499 pointer when asked to
 500 allocate zero bytes is a silly response to a silly question.