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