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.\" $OpenBSD: malloc.3,v 1.18 2000/01/19 05:36:38 pjanzen Exp $ 37.\" 38.Dd August 27, 1996 39.Dt MALLOC 3 40.Os 41.Sh NAME 42.Nm malloc , 43.Nm calloc , 44.Nm realloc , 45.Nm free , 46.Nm cfree 47.Nd memory allocation and deallocation 48.Sh SYNOPSIS 49.Fd #include <stdlib.h> 50.Ft void * 51.Fn malloc "size_t size" 52.Ft void * 53.Fn calloc "size_t nmemb" "size_t size" 54.Ft void * 55.Fn realloc "void *ptr" "size_t size" 56.Ft void 57.Fn free "void *ptr" 58.Ft void 59.Fn cfree "void *ptr" 60.Ft char * 61.Va malloc_options 62.Sh DESCRIPTION 63The 64.Fn malloc 65function allocates uninitialized space for an object whose 66size is specified by 67.Fa size . 68The 69.Fn malloc 70function maintains multiple lists of free blocks according to size, allocating 71space from the appropriate list. 72.Pp 73The allocated space is 74suitably aligned (after possible pointer 75coercion) for storage of any type of object. If the space is of 76.Em pagesize 77or larger, the memory returned will be page-aligned. 78.Pp 79Allocation of a zero size object returns a pointer to a zero size object. 80.Pp 81The 82.Fn calloc 83function allocates space for an array of 84.Fa nmemb 85objects, each of whose size is 86.Fa size . 87The space is initialized to all bits zero. 88.Pp 89The 90.Fn free 91function causes the space pointed to by 92.Fa ptr 93to be deallocated, that is, at least made available for further allocation, 94but if possible, it will passed back to the kernel with 95.Xr sbrk 2 . 96If 97.Fa ptr 98is a null pointer, no action occurs. 99.Pp 100A 101.Fn cfree 102function is also provided for compatibility with old systems and other 103.Nm malloc 104libraries; it is simply an alias for 105.Fn free . 106.Pp 107The 108.Fn realloc 109function changes the size of the object pointed to by 110.Fa ptr 111to 112.Fa size 113bytes and returns a pointer to the (possibly moved) object. 114The contents of the object are unchanged up to the lesser 115of the new and old sizes. 116If the new size is larger, the value of the newly allocated portion 117of the object is indeterminate and uninitialized. 118If 119.Fa ptr 120is a null pointer, the 121.Fn realloc 122function behaves like the 123.Fn malloc 124function for the specified size. 125If the space cannot be allocated, the object 126pointed to by 127.Fa ptr 128is unchanged. 129If 130.Fa size 131is zero and 132.Fa ptr 133is not a null pointer, the object it points to is freed and a new zero size 134object is returned. 135.Pp 136When using 137.Fn realloc 138one must be careful to avoid the following idiom: 139.Pp 140.Bd -literal -offset indent 141if ((p = realloc(p, nsize)) == NULL) 142 return NULL; 143.Ed 144.Pp 145In most cases, this will result in a leak of memory. 146As stated earlier, a return value of 147.Dv NULL 148indicates that the old object still remains allocated. 149Better code looks like this: 150.Bd -literal -offset indent 151if ((p2 = realloc(p, nsize)) == NULL) { 152 if (p) 153 free(p); 154 p = NULL; 155 return NULL; 156} 157p = p2; 158.Ed 159.Pp 160Malloc will first look for a symbolic link called 161.Pa /etc/malloc.conf 162and next check the environment for a variable called 163.Ev MALLOC_OPTIONS 164and finally for the global variable 165.Va malloc_options 166and scan them for flags in that order. 167Flags are single letters, uppercase means on, lowercase means off. 168.Bl -tag -width indent 169.It A 170``abort'' malloc will coredump the process, rather than tolerate failure. 171This is a very handy debugging aid, since the core file will represent the 172time of failure, 173rather than when the null pointer was accessed. 174.Pp 175.It D 176``dump'' malloc will dump statistics in a file called ``malloc.out'' at exit. 177This option requires the library to have been compiled with -DMALLOC_STATS in 178order to have any effect. 179.Pp 180.It J 181``junk'' fill some junk into the area allocated. 182Currently junk is bytes of 0xd0, this is pronounced ``Duh'' :-) 183.Pp 184.It H 185``hint'' pass a hint to the kernel about pages we don't use. If the 186machine is paging a lot this may help a bit. 187.Pp 188.It N 189Do not output warning messages when encountering possible corruption 190or bad pointers. 191.Pp 192.It R 193``realloc'' always reallocate when 194.Fn realloc 195is called, even if the initial allocation was big enough. 196This can substantially aid in compacting memory. 197.Pp 198.It U 199``utrace'' generate entries for 200.Xr ktrace 1 201for all operations. 202Consult the source for this one. 203.Pp 204.It X 205``xmalloc'' 206rather than return failure, 207.Xr abort 3 208the program with a diagnostic message on stderr. 209It is the intention that this option be set at compile time by 210including in the source: 211.Bd -literal -offset indent 212extern char *malloc_options; 213malloc_options = "X"; 214.Ed 215.Pp 216.It Z 217``zero'' fill some junk into the area allocated (see ``J''), 218except for the exact length the user asked for, which is zeroed. 219.Pp 220.It < 221``Half the cache size'' Reduce the size of the cache by a factor of two. 222.Pp 223.It > 224``Double the cache size'' Double the size of the cache by a factor of two. 225.El 226.Pp 227So to set a systemwide reduction of cache size and coredumps on problems 228one would: 229.Li ln -s 'A<' /etc/malloc.conf 230.Pp 231The ``J'' and ``Z'' is mostly for testing and debugging, 232if a program changes behavior if either of these options are used, 233it is buggy. 234.Pp 235The default cache size is 16 pages. 236.Sh ENVIRONMENT 237See above. 238.Sh RETURN VALUES 239The 240.Fn malloc 241and 242.Fn calloc 243functions return 244a pointer to the allocated space if successful; otherwise, 245a null pointer is returned and 246.Va errno 247is set to 248.Er ENOMEM . 249.Pp 250The 251.Fn free 252and 253.Fn cfree 254functions return no value. 255.Pp 256The 257.Fn realloc 258function returns a pointer to the (possibly moved) allocated space 259if successful; otherwise, a null pointer is returned and 260.Va errno 261is set to 262.Er ENOMEM . 263.Sh MESSAGES 264If 265.Fn malloc , 266.Fn calloc , 267.Fn realloc 268or 269.Fn free 270detect an error or warning condition, 271a message will be printed to file descriptor 2722 (not using stdio). 273Errors will always result in the process being 274.Xr abort 3 'ed. 275If the ``A'' option has been specified, warnings will also 276.Xr abort 3 277the process. 278.Pp 279Here is a brief description of the error messages and what they mean: 280.Pp 281``(ES): mumble mumble mumble'': 282malloc have been compiled with -DEXTRA_SANITY and something looks 283fishy in there. Consult sources and or wizards. 284.Pp 285``allocation failed'' 286if the ``A'' option is specified it is an error for 287.Fn malloc , 288.Fn calloc 289or 290.Fn realloc 291to return 292.Dv NULL . 293.Pp 294``mmap(2) failed, check limits.'' 295This is a rather weird condition that is most likely to mean that 296the system is seriously overloaded or that your ulimits are sick. 297.Pp 298``freelist is destroyed.'' 299mallocs internal freelist has been stomped on. 300.Pp 301Here is a brief description of the warning messages and what they mean: 302.Pp 303``chunk/page is already free.'' 304A pointer to a free chunk is attempted freed again. 305.Pp 306``junk pointer, too high to make sense.'' 307The pointer doesn't make sense. It's above the area of memory that 308.Fn malloc 309knows something about. 310This could be a pointer from some 311.Xr mmap 2 'ed 312memory. 313.Pp 314``junk pointer, too low to make sense.'' 315The pointer doesn't make sense. It's below the area of memory that 316.Fn malloc 317knows something about. 318This pointer probably came from your data or bss segments. 319.Pp 320``malloc() has never been called.'' 321Nothing has ever been allocated, yet something is being freed or 322realloc'ed. 323.Pp 324``modified (chunk-/page-) pointer.'' 325The pointer passed to free or realloc has been modified. 326.Pp 327``pointer to wrong page.'' 328The pointer that 329.Fn malloc 330is trying to free is not pointing to 331a sensible page. 332.Pp 333``recursive call.'' 334You have tried to call recursively into these functions. 335I can only imagine this as happening if you call one of these 336functions from a signal handler, which happens to be called 337while you're already in here. 338Well, sorry to say: that's not supported. 339If this is a problem for you I'd like to hear about it. It 340would be possible to add a sigblock() around this package, 341but it would have a performance penalty that is not acceptable 342as the default. 343.Pp 344``unknown char in MALLOC_OPTIONS'' 345we found something we didn't understand. 346.Sh FILES 347.Bl -tag -width "/etc/malloc.conf" 348.It Pa /etc/malloc.conf 349symbolic link to file containing option flags 350.El 351.Sh SEE ALSO 352.Xr brk 2 , 353.Xr alloca 3 , 354.Xr getpagesize 3 , 355.Xr memory 3 356.Pa /usr/share/doc/papers/malloc.ascii.gz 357.Sh STANDARDS 358The 359.Fn malloc 360function conforms to 361.St -ansiC . 362.Sh HISTORY 363The present implementation of 364.Fn malloc 365started out as a filesystem on a drum 366attached to a 20-bit binary challenged computer built with discrete germanium 367transistors, and it has since graduated to handle primary storage rather than 368secondary. 369.Pp 370The main difference from other 371.Fn malloc 372implementations are believed to be that 373the free pages are not accessed until allocated. 374Most 375.Fn malloc 376implementations will store a data structure containing a, 377possibly double-, linked list in the free chunks of memory, used to tie 378all the free memory together. 379That is a quite suboptimal thing to do. 380Every time the free-list is traversed, all the otherwise unused, and very 381likely paged out, pages get faulted into primary memory, just to see what 382lies after them in the list. 383.Pp 384On systems which are paging, this can make a factor five in difference on the 385page-faults of a process. 386