1.\" $OpenBSD: malloc.9,v 1.36 2005/12/14 22:03:00 pedro Exp $ 2.\" $NetBSD: malloc.9,v 1.2 1996/10/30 05:29:54 lukem Exp $ 3.\" 4.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Paul Kranenburg. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 30.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd August 6, 2005 39.Dt MALLOC 9 40.Os 41.Sh NAME 42.Nm malloc 43.Nd kernel memory allocator 44.Sh SYNOPSIS 45.Fd #include <sys/types.h> 46.Fd #include <sys/malloc.h> 47.Ft void * 48.Fn malloc "unsigned long size" "int type" "int flags" 49.Fn MALLOC "space" "cast" "unsigned long size" "int type" "int flags" 50.Ft void 51.Fn free "void *addr" "int type" 52.Fn FREE "void *addr" "int type" 53.Sh DESCRIPTION 54The 55.Fn malloc 56function allocates uninitialized memory in kernel address space for an 57object whose size is specified by 58.Fa size . 59.Fn free 60releases memory at address 61.Fa addr 62that was previously allocated by 63.Fn malloc 64for re-use. 65The 66.Fn MALLOC 67macro variant is functionally equivalent to 68.Bd -literal -offset indent 69(space) = (cast)malloc((u_long)(size), type, flags) 70.Ed 71.Pp 72and the 73.Fn FREE 74macro variant is equivalent to 75.Bd -literal -offset indent 76free((caddr_t)(addr), type) 77.Ed 78.Pp 79These macros should only be used when the 80.Fa size 81argument is a constant. 82.Pp 83Unlike its standard C library counterpart 84.Pq Xr malloc 3 , 85the kernel version takes two more arguments. 86The 87.Fa flags 88argument further qualifies 89.Fn malloc Ns 's 90operational characteristics as follows: 91.Bl -tag -width xxx -offset indent 92.It Dv M_WAITOK 93This is defined to be 0, and is therefore most useful as an aid to code 94readability. 95In effect, it is the same as having no other 96.Fa flags 97specified. 98If memory is currently unavailable, 99.Fn malloc 100may call sleep to wait for resources to be released by other processes. 101.It Dv M_NOWAIT 102Causes 103.Fn malloc 104to return 105.Dv NULL 106if the request cannot be immediately fulfilled due to resource shortage. 107.It Dv M_CANFAIL 108In the 109.Dv M_WAITOK 110case, if not enough memory is available, return 111.Dv NULL 112instead of calling 113.Xr panic 9 . 114.Dv M_CANFAIL 115has no effect if 116.Dv M_NOWAIT 117is specified. 118.El 119.Pp 120The 121.Fa type 122argument broadly identifies the kernel subsystem for which the allocated 123memory was needed, and is commonly used to maintain statistics about 124kernel memory usage. 125The following types are currently defined: 126.Pp 127.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 128.It Dv M_FREE 129Should be on free list. 130.It Dv M_MBUF 131Mbuf memory. 132.It Dv M_DEVBUF 133Device driver memory. 134.It Dv M_DEBUG 135.Nm malloc 136debug structures. 137.It Dv M_PCB 138Protocol control blocks. 139.It Dv M_RTABLE 140Routing tables. 141.It Dv M_FTABLE 142Fragment reassembly headers. 143.It Dv M_IFADDR 144Interface addresses. 145.It Dv M_SOOPTS 146Socket options. 147.It Dv M_SYSCTL 148Sysctl persistent buffers. 149.It Dv M_IOCTLOPS 150Ioctl data buffers. 151.It Dv M_IOV 152Large IOVs. 153.It Dv M_MOUNT 154VFS mount structs. 155.It Dv M_NFSREQ 156NFS request headers. 157.It Dv M_NFSMNT 158NFS mount structures. 159.It Dv M_NFSNODE 160NFS vnode private part. 161.It Dv M_VNODE 162Dynamically allocated vnodes. 163.It Dv M_CACHE 164Dynamically allocated cache entries. 165.It Dv M_DQUOT 166UFS quota entries. 167.It Dv M_UFSMNT 168UFS mount structures. 169.It Dv M_SHM 170SVID compatible shared memory segments. 171.It Dv M_VMMAP 172VM map structures. 173.It Dv M_SEM 174SVID compatible semaphores. 175.It Dv M_DIRHASH 176UFS directory hash structures. 177.It Dv M_VMPMAP 178VM pmap data. 179.It Dv M_FILE 180Open file structures. 181.It Dv M_FILEDESC 182Open file descriptor tables. 183.It Dv M_PROC 184Proc structures. 185.It Dv M_SUBPROC 186Proc sub-structures. 187.It Dv M_VCLUSTER 188Cluster for VFS. 189.It Dv M_MFSNODE 190MFS vnode private part. 191.It Dv M_NETADDR 192Export host address structures. 193.It Dv M_NFSSVC 194NFS server structures. 195.It Dv M_NFSUID 196NFS uid mapping structures. 197.It Dv M_NFSD 198NFS server daemon structures. 199.It Dv M_IPMOPTS 200Internet multicast options. 201.It Dv M_IPMADDR 202Internet multicast addresses. 203.It Dv M_IFMADDR 204Link-level multicast addresses. 205.It Dv M_MRTABLE 206Multicast routing tables. 207.It Dv M_ISOFSMNT 208ISOFS mount structures. 209.It Dv M_ISOFSNODE 210ISOFS vnode private part. 211.It Dv M_MSDOSFSMNT 212MSDOS FS mount structures. 213.It Dv M_MSDOSFSFAT 214MSDOS FS FAT tables. 215.It Dv M_MSDOSFSNODE 216MSDOS FS vnode private part. 217.It Dv M_TTYS 218Allocated tty structures. 219.It Dv M_EXEC 220Argument lists & other mem used by exec. 221.It Dv M_MISCFSMNT 222Misc. FS mount structures. 223.It Dv M_ADOSFSMNT 224ADOSFS mount structures. 225.It Dv M_ANODE 226ADOSFS anode structures and tables. 227.It Dv M_ADOSFSBITMAP 228ADOSFS bitmap. 229.It Dv M_PFKEY 230Pfkey data. 231.It Dv M_TDB 232Transforms database. 233.It Dv M_XDATA 234IPsec data. 235.It Dv M_PAGEDEP 236File page dependencies. 237.It Dv M_INODEDEP 238Inode dependencies. 239.It Dv M_NEWBLK 240New block allocation. 241.It Dv M_RAIDFRAME 242RAIDframe data. 243.It Dv M_UVMAMAP 244UVM amap and related. 245.It Dv M_UVMAOBJ 246UVM aobj and related. 247.It Dv M_USB 248USB general. 249.It Dv M_USBDEV 250USB device driver. 251.It Dv M_USBHC 252USB host controller. 253.It Dv M_MEMDESC 254Memory range. 255.It Dv M_CRYPTO_DATA 256.Xr crypto 4 257data buffers. 258.It Dv M_CREDENTIALS 259.Xr ipsec 4 260related credentials. 261.It Dv M_PACKET_TAGS 262Packet-attached information tags. 263.It Dv M1394CTL 264IEEE 1394 control structures. 265.It Dv M1394DATA 266IEEE 1394 data buffers. 267.It Dv M_EMULDATA 268Per process emulation data. 269.It Dv M_IP6OPT 270IPv6 options. 271.It Dv M_IP6NDP 272IPv6 neighbour discovery structures. 273.It Dv M_IP6RR 274IPv6 router renumbering prefix. 275.It Dv M_RR_ADDR 276IPv6 router renumbering interface identifiers. 277.It Dv M_TEMP 278Miscellaneous temporary data buffers. 279.It Dv M_NTFSMNT 280NTFS mount structures. 281.It Dv M_NTFSNTNODE 282NTFS ntnode information. 283.It Dv M_NTFSNODE 284NTFS fnode information. 285.It Dv M_NTFSDIR 286NTFS directory buffers. 287.It Dv M_NTFSHASH 288NTFS ntnode hash tables. 289.It Dv M_NTFSVATTR 290NTFS file attribute information. 291.It Dv M_NTFSRDATA 292NTFS resident data. 293.It Dv M_NTFSDECOMP 294NTFS decompression temporary storage. 295.It Dv M_NTFSRUN 296NTFS vrun storage. 297.It Dv M_KEVENT 298.Xr kqueue 2 299data structures. 300.It Dv M_BLUETOOTH 301Bluetooth data structures. 302.It Dv M_BWMETER 303Multicast upcall bandwidth meters. 304.It Dv M_UDFMOUNT 305UDF mount structures. 306.It Dv M_UDFFENTRY 307UDF file entries. 308.It Dv M_UDFFID 309UDF file ids. 310.El 311.Pp 312Statistics based on the 313.Fa type 314argument are maintained only if the kernel option 315.Dv KMEMSTATS 316is used when compiling the kernel 317.Po the default in current\ \& 318.Ox 319kernels 320.Pc 321and can be examined by using 322.Sq vmstat -m . 323.Sh RETURN VALUES 324.Fn malloc 325returns a kernel virtual address that is suitably aligned for storage of 326any type of object. 327.Sh DIAGNOSTICS 328A kernel compiled with the 329.Dv DIAGNOSTIC 330configuration option attempts to detect memory corruption caused by 331such things as writing outside the allocated area and unbalanced calls to the 332.Fn malloc 333and 334.Fn free 335functions. 336Failing consistency checks will cause a panic or a system console message: 337.Bl -bullet -offset indent -compact 338.Pp 339.It 340panic: 341.Dq malloc - bogus type 342.It 343panic: 344.Dq malloc: out of space in kmem_map 345.It 346panic: 347.Dq malloc: allocation too large 348.It 349panic: 350.Dq malloc: wrong bucket 351.It 352panic: 353.Dq malloc: lost data 354.It 355panic: 356.Dq free: unaligned addr 357.It 358panic: 359.Dq free: duplicated free 360.It 361panic: 362.Dq free: multiple frees 363.It 364panic: 365.Dq kmeminit: minbucket too small/struct freelist too big 366.It 367.Dq multiply freed item Aq addr 368.It 369.Dq Data modified on freelist: Aq data object description 370.El 371.Sh DEBUGGING 372A kernel compiled with the 373.Cm MALLOC_DEBUG 374option allows for more extensive debugging of memory allocations. 375The 376.Va debug_malloc_type , 377.Va debug_malloc_size , 378.Va debug_malloc_size_lo 379and 380.Va debug_malloc_size_hi 381variables choose which allocation to debug. 382.Va debug_malloc_type 383should be set to the memory type and 384.Va debug_malloc_size 385should be set to the memory size to debug. 3860 can be used as a wildcard. 387.Va debug_malloc_size_lo 388and 389.Va debug_malloc_size_hi 390can be used to specify a range of sizes if the exact size to debug is not 391known. 392When those are used, 393.Va debug_malloc_size 394needs to be set to the wildcard. 395.Dv M_DEBUG 396can also be specified as an allocation type to force allocation with 397debugging. 398.Pp 399Every call to 400.Fn malloc 401with a memory type and size that matches the debugged type and size will 402allocate two virtual pages. 403The pointer returned will be aligned so that 404the requested area will end at the page boundary and the second virtual page 405will be left unmapped. 406This way we can catch reads and writes outside the allocated area. 407.Pp 408Every call to 409.Fn free 410with memory that was returned by the debugging malloc will cause the memory 411area to become unmapped so that we can catch dangling reads and writes to 412freed memory. 413.Pp 414There are no special diagnostics if any errors are caught by the debugging 415malloc. 416The errors will look like normal access to unmapped memory. 417On a memory access error, the 418.Ic show malloc 419command in 420.Xr ddb 4 421can be invoked to see what memory areas are allocated and freed. 422If the faulting address is within two pages from an address on the allocated 423list, there was an access outside the allocated area. 424If the faulting address is within two pages from an address on the free list, 425there was an access to freed memory. 426.Pp 427Care needs to be taken when using the 428.Cm MALLOC_DEBUG 429option: the memory consumption can run away pretty quickly and there is 430a severe performance degradation when allocating and freeing debugged memory 431types. 432.Sh SEE ALSO 433.Xr vmstat 8 434