1.\" $OpenBSD: malloc.9,v 1.30 2004/01/14 19:34:05 grange 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 June 16, 1996 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_NOWAIT 93Causes 94.Fn malloc 95to return 96.Dv NULL 97if the request cannot be immediately fulfilled due to resource shortage. 98Otherwise, 99.Fn malloc 100may call sleep to wait for resources to be released by other processes. 101If this flag is not set, 102.Fn malloc 103will never return 104.Dv NULL . 105Note that 106.Dv M_WAITOK 107is conveniently defined to be 0, and hence maybe or'ed into the 108.Fa flags 109argument to indicate that it's OK to wait for resources. 110.El 111.Pp 112Currently, only one flag is defined. 113.Pp 114The 115.Fa type 116argument broadly identifies the kernel subsystem for which the allocated 117memory was needed, and is commonly used to maintain statistics about 118kernel memory usage. 119The following types are currently defined: 120.Pp 121.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 122.It Dv M_FREE 123Should be on free list. 124.It Dv M_MBUF 125Mbuf memory. 126.It Dv M_DEVBUF 127Device driver memory. 128.It Dv M_DEBUG 129.Nm malloc 130debug structures. 131.It Dv M_PCB 132Protocol control blocks. 133.It Dv M_RTABLE 134Routing tables. 135.It Dv M_FTABLE 136Fragment reassembly headers. 137.It Dv M_IFADDR 138Interface addresses. 139.It Dv M_SOOPTS 140Socket options. 141.It Dv M_SYSCTL 142Sysctl persistent buffers. 143.It Dv M_NAMEI 144Namei path name buffers. 145.It Dv M_IOCTLOPS 146Ioctl data buffers. 147.It Dv M_IOV 148Large IOVs. 149.It Dv M_MOUNT 150VFS mount structs. 151.It Dv M_NFSREQ 152NFS request headers. 153.It Dv M_NFSMNT 154NFS mount structures. 155.It Dv M_NFSNODE 156NFS vnode private part. 157.It Dv M_VNODE 158Dynamically allocated vnodes. 159.It Dv M_CACHE 160Dynamically allocated cache entries. 161.It Dv M_DQUOT 162UFS quota entries. 163.It Dv M_UFSMNT 164UFS mount structures. 165.It Dv M_SHM 166SVID compatible shared memory segments. 167.It Dv M_VMMAP 168VM map structures. 169.It Dv M_VMPMAP 170VM pmap data. 171.It Dv M_FILE 172Open file structures. 173.It Dv M_FILEDESC 174Open file descriptor tables. 175.It Dv M_PROC 176Proc structures. 177.It Dv M_SUBPROC 178Proc sub-structures. 179.It Dv M_VCLUSTER 180Cluster for VFS. 181.It Dv M_MFSNODE 182MFS vnode private part. 183.It Dv M_NETADDR 184Export host address structures. 185.It Dv M_NFSSVC 186NFS server structures. 187.It Dv M_NFSUID 188NFS uid mapping structures. 189.It Dv M_NFSD 190NFS server daemon structures. 191.It Dv M_IPMOPTS 192Internet multicast options. 193.It Dv M_IPMADDR 194Internet multicast addresses. 195.It Dv M_IFMADDR 196Link-level multicast addresses. 197.It Dv M_MRTABLE 198Multicast routing tables. 199.It Dv M_ISOFSMNT 200ISOFS mount structures. 201.It Dv M_ISOFSNODE 202ISOFS vnode private part. 203.It Dv M_MSDOSFSMNT 204MSDOS FS mount structures. 205.It Dv M_MSDOSFSFAT 206MSDOS FS FAT tables. 207.It Dv M_MSDOSFSNODE 208MSDOS FS vnode private part. 209.It Dv M_TTYS 210Allocated tty structures. 211.It Dv M_EXEC 212Argument lists & other mem used by exec. 213.It Dv M_MISCFSMNT 214Misc. FS mount structures. 215.It Dv M_ADOSFSMNT 216ADOSFS mount structures. 217.It Dv M_ANODE 218ADOSFS anode structures and tables. 219.It Dv M_ADOSFSBITMAP 220ADOSFS bitmap. 221.It Dv M_EXT2FSNODE 222EXT2FS vnode private part. 223.It Dv M_PFKEY 224Pfkey data. 225.It Dv M_TDB 226Transforms database. 227.It Dv M_XDATA 228IPsec data. 229.It Dv M_VFS 230VFS file systems. 231.It Dv M_PAGEDEP 232File page dependencies. 233.It Dv M_INODEDEP 234Inode dependencies. 235.It Dv M_NEWBLK 236New block allocation. 237.It Dv M_VMSWAP 238VM swap structures. 239.It Dv M_RAIDFRAME 240RAIDframe data. 241.It Dv M_UVMAMAP 242UVM amap and related. 243.It Dv M_UVMAOBJ 244UVM aobj and related. 245.It Dv M_USB 246USB general. 247.It Dv M_USBDEV 248USB device driver. 249.It Dv M_USBHC 250USB host controller. 251.It Dv M_MEMDESC 252Memory range. 253.It Dv M_UFS_EXTATTR 254UFS Extended Attributes. 255.It Dv M_CREDENTIALS 256.Xr ipsec 4 257related credentials. 258.It Dv M_PACKET_TAGS 259Packet-attached information tags. 260.It Dv M1394CTL 261IEEE 1394 control structures. 262.It Dv M1394DATA 263IEEE 1394 data buffers. 264.It Dv M_EMULDATA 265Per process emulation data. 266.It Dv M_IP6OPT 267IPv6 options. 268.It Dv M_IP6NDP 269IPv6 neighbour discovery structures. 270.It Dv M_IP6RR 271IPv6 router renumbering prefix. 272.It Dv M_RR_ADDR 273IPv6 router renumbering interface identifiers. 274.It Dv M_TEMP 275Miscellaneous temporary data buffers. 276.It Dv M_NTFSMNT 277NTFS mount structures. 278.It Dv M_NTFSNTNODE 279NTFS ntnode information. 280.It Dv M_NTFSNODE 281NTFS fnode information. 282.It Dv M_NTFSDIR 283NTFS directory buffers. 284.It Dv M_NTFSHASH 285NTFS ntnode hash tables. 286.It Dv M_NTFSVATTR 287NTFS file attribute information. 288.It Dv M_NTFSRDATA 289NTFS resident data. 290.It Dv M_NTFSDECOMP 291NTFS decompression temporary storage. 292.It Dv M_NTFSRUN 293NTFS vrun storage. 294.El 295.Pp 296Statistics based on the 297.Fa type 298argument are maintained only if the kernel option 299.Dv KMEMSTATS 300is used when compiling the kernel 301.Po the default in current\ \& 302.Ox 303kernels 304.Pc 305and can be examined by using 306.Sq vmstat -m . 307.Sh RETURN VALUES 308.Fn malloc 309returns a kernel virtual address that is suitably aligned for storage of 310any type of object. 311.Sh DIAGNOSTICS 312A kernel compiled with the 313.Dv DIAGNOSTIC 314configuration option attempts to detect memory corruption caused by 315such things as writing outside the allocated area and unbalanced calls to the 316.Fn malloc 317and 318.Fn free 319functions. 320Failing consistency checks will cause a panic or a system console message: 321.Bl -bullet -offset indent -compact 322.Pp 323.It 324panic: 325.Dq malloc - bogus type 326.It 327panic: 328.Dq malloc: out of space in kmem_map 329.It 330panic: 331.Dq malloc: allocation too large 332.It 333panic: 334.Dq malloc: wrong bucket 335.It 336panic: 337.Dq malloc: lost data 338.It 339panic: 340.Dq free: unaligned addr 341.It 342panic: 343.Dq free: duplicated free 344.It 345panic: 346.Dq free: multiple frees 347.It 348panic: 349.Dq kmeminit: minbucket too small/struct freelist too big 350.It 351.Dq multiply freed item Aq addr 352.It 353.Dq Data modified on freelist: Aq data object description 354.El 355.Sh DEBUGGING 356A kernel compiled with the 357.Cm MALLOC_DEBUG 358option allows for more extensive debugging of memory allocations. 359The 360.Va debug_malloc_type , 361.Va debug_malloc_size , 362.Va debug_malloc_size_lo 363and 364.Va debug_malloc_size_hi 365variables choose which allocation to debug. 366.Va debug_malloc_type 367should be set to the memory type and 368.Va debug_malloc_size 369should be set to the memory size to debug. 3700 can be used as a wildcard. 371.Va debug_malloc_size_lo 372and 373.Va debug_malloc_size_hi 374can be used to specify a range of sizes if the exact size to debug is not 375known. 376When those are used, 377.Va debug_malloc_size 378needs to be set to the wildcard. 379.Dv M_DEBUG 380can also be specified as an allocation type to force allocation with 381debugging. 382.Pp 383Every call to 384.Fn malloc 385with a memory type and size that matches the debugged type and size will 386allocate two virtual pages. 387The pointer returned will be aligned so that 388the requested area will end at the page boundary and the second virtual page 389will be left unmapped. 390This way we can catch reads and writes outside the allocated area. 391.Pp 392Every call to 393.Fn free 394with memory that was returned by the debugging malloc will cause the memory 395area to become unmapped so that we can catch dangling reads and writes to 396freed memory. 397.Pp 398There are no special diagnostics if any errors are caught by the debugging 399malloc. 400The errors will look like normal access to unmapped memory. 401On a memory access error, the 402.Ic show malloc 403command in 404.Xr ddb 4 405can be invoked to see what memory areas are allocated and freed. 406If the faulting address is within two pages from an address on the allocated 407list, there was an access outside the allocated area. 408If the faulting address is within two pages from an address on the free list, 409there was an access to freed memory. 410.Pp 411Care needs to be taken when using the 412.Cm MALLOC_DEBUG 413option: the memory consumption can run away pretty quickly and there is 414a severe performance degradation when allocating and freeing debugged memory 415types. 416.Sh SEE ALSO 417.Xr vmstat 8 418