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