1.\" 2.\" Copyright (c) 1980, 1991, 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" the American National Standards Committee X3, on Information 7.\" Processing Systems. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" $OpenBSD: malloc.3,v 1.28 2003/06/02 20:18:37 millert Exp $ 34.\" 35.Dd August 27, 1996 36.Dt MALLOC 3 37.Os 38.Sh NAME 39.Nm malloc , 40.Nm calloc , 41.Nm realloc , 42.Nm free , 43.Nm cfree 44.Nd memory allocation and deallocation 45.Sh SYNOPSIS 46.Fd #include <stdlib.h> 47.Ft void * 48.Fn malloc "size_t size" 49.Ft void * 50.Fn calloc "size_t nmemb" "size_t size" 51.Ft void * 52.Fn realloc "void *ptr" "size_t size" 53.Ft void 54.Fn free "void *ptr" 55.Ft void 56.Fn cfree "void *ptr" 57.Ft char * 58.Va malloc_options 59.Sh DESCRIPTION 60The 61.Fn malloc 62function allocates uninitialized space for an object whose 63size is specified by 64.Fa size . 65The 66.Fn malloc 67function maintains multiple lists of free blocks according to size, allocating 68space from the appropriate list. 69.Pp 70The allocated space is 71suitably aligned (after possible pointer 72coercion) for storage of any type of object. 73If the space is of 74.Em pagesize 75or larger, the memory returned will be page-aligned. 76.Pp 77Allocation of a zero size object returns a pointer to a zero size object. 78This zero size object is access protected, so any access to it will 79generate an exception (SIGSEGV). 80Many zero-sized objects can be placed consecutively in shared 81protected pages. 82The minimum size of the protection on each object is suitably aligned and 83sized as previously stated, but the protection may extend further depending 84on where in a protected zone the object lands. 85.Pp 86The 87.Fn calloc 88function allocates space for an array of 89.Fa nmemb 90objects, each of whose size is 91.Fa size . 92The space is initialized to all bits zero. 93.Pp 94The 95.Fn free 96function causes the space pointed to by 97.Fa ptr 98to be deallocated, that is, at least made available for further allocation, 99but if possible, it will passed back to the kernel with 100.Xr sbrk 2 . 101If 102.Fa ptr 103is a null pointer, no action occurs. 104.Pp 105A 106.Fn cfree 107function is also provided for compatibility with old systems and other 108.Nm malloc 109libraries; it is simply an alias for 110.Fn free . 111.Pp 112The 113.Fn realloc 114function changes the size of the object pointed to by 115.Fa ptr 116to 117.Fa size 118bytes and returns a pointer to the (possibly moved) object. 119The contents of the object are unchanged up to the lesser 120of the new and old sizes. 121If the new size is larger, the value of the newly allocated portion 122of the object is indeterminate and uninitialized. 123If 124.Fa ptr 125is a null pointer, the 126.Fn realloc 127function behaves like the 128.Fn malloc 129function for the specified size. 130If the space cannot be allocated, the object 131pointed to by 132.Fa ptr 133is unchanged. 134If 135.Fa size 136is zero and 137.Fa ptr 138is not a null pointer, the object it points to is freed and a new zero size 139object is returned. 140.Pp 141When using 142.Fn realloc 143one must be careful to avoid the following idiom: 144.Pp 145.Bd -literal -offset indent 146if ((p = realloc(p, nsize)) == NULL) 147 return NULL; 148.Ed 149.Pp 150In most cases, this will result in a leak of memory. 151As stated earlier, a return value of 152.Dv NULL 153indicates that the old object still remains allocated. 154Better code looks like this: 155.Bd -literal -offset indent 156if ((p2 = realloc(p, nsize)) == NULL) { 157 if (p) 158 free(p); 159 p = NULL; 160 return NULL; 161} 162p = p2; 163.Ed 164.Pp 165Malloc will first look for a symbolic link called 166.Pa /etc/malloc.conf 167and next check the environment for a variable called 168.Ev MALLOC_OPTIONS 169and finally for the global variable 170.Va malloc_options 171and scan them for flags in that order. 172Flags are single letters, uppercase means on, lowercase means off. 173.Bl -tag -width indent 174.It Cm A 175.Dq Abort . 176.Fn malloc 177will coredump the process, rather than tolerate failure. 178This is a very handy debugging aid, since the core file will represent the 179time of failure, rather than when the null pointer was accessed. 180.Pp 181.It Cm D 182.Dq Dump . 183.Fn malloc 184will dump statistics in a file called 185.Pa malloc.out 186at exit. 187This option requires the library to have been compiled with -DMALLOC_STATS in 188order to have any effect. 189.Pp 190.It Cm J 191.Dq Junk . 192Fill some junk into the area allocated. 193Currently junk is bytes of 0xd0; this is pronounced 194.Dq Duh . 195\&:-) 196.Pp 197.It Cm H 198.Dq Hint . 199Pass a hint to the kernel about pages we don't use. 200If the machine is paging a lot this may help a bit. 201.Pp 202.It Cm N 203Do not output warning messages when encountering possible corruption 204or bad pointers. 205.Pp 206.It Cm R 207.Dq realloc . 208Always reallocate when 209.Fn realloc 210is called, even if the initial allocation was big enough. 211This can substantially aid in compacting memory. 212.\".Pp 213.\".It Cm U 214.\".Dq utrace . 215.\"Generate entries for 216.\".Xr ktrace 1 217.\"for all operations. 218.\"Consult the source for this one. 219.Pp 220.It Cm X 221.Dq xmalloc . 222Rather than return failure, 223.Xr abort 3 224the program with a diagnostic message on stderr. 225It is the intention that this option be set at compile time by 226including in the source: 227.Bd -literal -offset indent 228extern char *malloc_options; 229malloc_options = "X"; 230.Ed 231.Pp 232.It Cm Z 233.Dq Zero . 234Fill some junk into the area allocated (see 235.Cm J ) , 236except for the exact length the user asked for, which is zeroed. 237.Pp 238.It Cm < 239.Dq Half the cache size . 240Reduce the size of the cache by a factor of two. 241.Pp 242.It Cm > 243.Dq Double the cache size . 244Double the size of the cache by a factor of two. 245.El 246.Pp 247So to set a systemwide reduction of cache size and coredumps on problems 248one would: 249.Li ln -s 'A<' /etc/malloc.conf 250.Pp 251The 252.Cm J 253and 254.Cm Z 255flags are mostly for testing and debugging. 256If a program changes behavior if either of these options are used, 257it is buggy. 258.Pp 259The default cache size is 16 pages. 260.Sh RETURN VALUES 261The 262.Fn malloc 263and 264.Fn calloc 265functions return a pointer to the allocated space if successful; otherwise, 266a null pointer is returned and 267.Va errno 268is set to 269.Er ENOMEM . 270.Pp 271The 272.Fn free 273and 274.Fn cfree 275functions return no value. 276.Pp 277The 278.Fn realloc 279function returns a pointer to the (possibly moved) allocated space 280if successful; otherwise, a null pointer is returned and 281.Va errno 282is set to 283.Er ENOMEM . 284.Sh ENVIRONMENT 285See above. 286.Sh FILES 287.Bl -tag -width "/etc/malloc.conf" 288.It Pa /etc/malloc.conf 289symbolic link to filename containing option flags 290.El 291.Sh DIAGNOSTICS 292If 293.Fn malloc , 294.Fn calloc , 295.Fn realloc , 296or 297.Fn free 298detect an error or warning condition, 299a message will be printed to file descriptor 3002 (not using stdio). 301Errors will always result in the process being 302.Xr abort 3 'ed. 303If the 304.Cm A 305option has been specified, warnings will also 306.Xr abort 3 307the process. 308.Pp 309Here is a brief description of the error messages and what they mean: 310.Bl -tag -width Fl 311.It Dq (ES): mumble mumble mumble 312.Fn malloc 313has been compiled with 314.Dv \&-DEXTRA_SANITY 315and something looks fishy in there. 316Consult sources and/or wizards. 317.It Dq allocation failed 318If the 319.Cm A 320option is specified it is an error for 321.Fn malloc , 322.Fn calloc , 323or 324.Fn realloc 325to return 326.Dv NULL . 327.It Dq mmap(2) failed, check limits. 328This is a rather weird condition that is most likely to indicate a 329seriously overloaded system or a 330.Xr ulimit 1 331restriction. 332.It Dq freelist is destroyed. 333.Fn malloc Ns 's 334internal freelist has been stomped on. 335.El 336.Pp 337Here is a brief description of the warning messages and what they mean: 338.Bl -tag -width Fl 339.It Dq chunk/page is already free. 340A pointer to a free chunk is attempted freed again. 341.It Dq junk pointer, too high to make sense. 342The pointer doesn't make sense. 343It's above the area of memory that 344.Fn malloc 345knows something about. 346This could be a pointer from some 347.Xr mmap 2 'ed 348memory. 349.It Dq junk pointer, too low to make sense. 350The pointer doesn't make sense. 351It's below the area of memory that 352.Fn malloc 353knows something about. 354This pointer probably came from your data or bss segments. 355.It Dq malloc() has never been called. 356Nothing has ever been allocated, yet something is being freed or 357realloc'ed. 358.It Dq modified (chunk-/page-) pointer. 359The pointer passed to free or realloc has been modified. 360.It Dq pointer to wrong page. 361The pointer that 362.Fn malloc 363is trying to free is not pointing to 364a sensible page. 365.It Dq recursive call. 366An attempt was made to call recursively into these functions, i.e., from a 367signal handler. 368This behavior is not supported. 369In particular, signal handlers should 370.Em not 371use any of the 372.Fn malloc 373functions nor utilize any other functions which may call 374.Fn malloc 375(e.g., 376.Xr stdio 3 377routines). 378.It Dq unknown char in MALLOC_OPTIONS 379We found something we didn't understand. 380.El 381.Sh SEE ALSO 382.Xr brk 2 , 383.Xr alloca 3 , 384.Xr getpagesize 3 , 385.Xr memory 3 386.Sh STANDARDS 387The 388.Fn malloc 389function conforms to 390.St -ansiC . 391.Sh HISTORY 392The present implementation of 393.Fn malloc 394started out as a filesystem on a drum 395attached to a 20-bit binary challenged computer built with discrete germanium 396transistors, and it has since graduated to handle primary storage rather than 397secondary. 398.Pp 399The main difference from other 400.Fn malloc 401implementations are believed to be that 402the free pages are not accessed until allocated. 403Most 404.Fn malloc 405implementations will store a data structure containing a, 406possibly double-, linked list in the free chunks of memory, used to tie 407all the free memory together. 408That is a quite suboptimal thing to do. 409Every time the free-list is traversed, all the otherwise unused, and very 410likely paged out, pages get faulted into primary memory, just to see what 411lies after them in the list. 412.Pp 413On systems which are paging, this can make a factor five in difference on the 414page-faults of a process. 415