1.\" $OpenBSD: malloc.9,v 1.29 2003/07/11 13:47:41 jmc 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_LOCKF 176Byte-range locking structures. 177.It Dv M_PROC 178Proc structures. 179.It Dv M_SUBPROC 180Proc sub-structures. 181.It Dv M_VCLUSTER 182Cluster for VFS. 183.It Dv M_MFSNODE 184MFS vnode private part. 185.It Dv M_NETADDR 186Export host address structures. 187.It Dv M_NFSSVC 188NFS server structures. 189.It Dv M_NFSUID 190NFS uid mapping structures. 191.It Dv M_NFSD 192NFS server daemon structures. 193.It Dv M_IPMOPTS 194Internet multicast options. 195.It Dv M_IPMADDR 196Internet multicast addresses. 197.It Dv M_IFMADDR 198Link-level multicast addresses. 199.It Dv M_MRTABLE 200Multicast routing tables. 201.It Dv M_ISOFSMNT 202ISOFS mount structures. 203.It Dv M_ISOFSNODE 204ISOFS vnode private part. 205.It Dv M_MSDOSFSMNT 206MSDOS FS mount structures. 207.It Dv M_MSDOSFSFAT 208MSDOS FS FAT tables. 209.It Dv M_MSDOSFSNODE 210MSDOS FS vnode private part. 211.It Dv M_TTYS 212Allocated tty structures. 213.It Dv M_EXEC 214Argument lists & other mem used by exec. 215.It Dv M_MISCFSMNT 216Misc. FS mount structures. 217.It Dv M_ADOSFSMNT 218ADOSFS mount structures. 219.It Dv M_ANODE 220ADOSFS anode structures and tables. 221.It Dv M_ADOSFSBITMAP 222ADOSFS bitmap. 223.It Dv M_EXT2FSNODE 224EXT2FS vnode private part. 225.It Dv M_PFKEY 226Pfkey data. 227.It Dv M_TDB 228Transforms database. 229.It Dv M_XDATA 230IPsec data. 231.It Dv M_VFS 232VFS file systems. 233.It Dv M_PAGEDEP 234File page dependencies. 235.It Dv M_INODEDEP 236Inode dependencies. 237.It Dv M_NEWBLK 238New block allocation. 239.It Dv M_VMSWAP 240VM swap structures. 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_UFS_EXTATTR 256UFS Extended Attributes. 257.It Dv M_CREDENTIALS 258.Xr ipsec 4 259related credentials. 260.It Dv M_PACKET_TAGS 261Packet-attached information tags. 262.It Dv M1394CTL 263IEEE 1394 control structures. 264.It Dv M1394DATA 265IEEE 1394 data buffers. 266.It Dv M_EMULDATA 267Per process emulation data. 268.It Dv M_IP6OPT 269IPv6 options. 270.It Dv M_IP6NDP 271IPv6 neighbour discovery structures. 272.It Dv M_IP6RR 273IPv6 router renumbering prefix. 274.It Dv M_RR_ADDR 275IPv6 router renumbering interface identifiers. 276.It Dv M_TEMP 277Miscellaneous temporary data buffers. 278.It Dv M_NTFSMNT 279NTFS mount structures. 280.It Dv M_NTFSNTNODE 281NTFS ntnode information. 282.It Dv M_NTFSNODE 283NTFS fnode information. 284.It Dv M_NTFSDIR 285NTFS directory buffers. 286.It Dv M_NTFSHASH 287NTFS ntnode hash tables. 288.It Dv M_NTFSVATTR 289NTFS file attribute information. 290.It Dv M_NTFSRDATA 291NTFS resident data. 292.It Dv M_NTFSDECOMP 293NTFS decompression temporary storage. 294.It Dv M_NTFSRUN 295NTFS vrun storage. 296.El 297.Pp 298Statistics based on the 299.Fa type 300argument are maintained only if the kernel option 301.Dv KMEMSTATS 302is used when compiling the kernel 303.Po the default in current\ \& 304.Ox 305kernels 306.Pc 307and can be examined by using 308.Sq vmstat -m . 309.Sh RETURN VALUES 310.Fn malloc 311returns a kernel virtual address that is suitably aligned for storage of 312any type of object. 313.Sh DIAGNOSTICS 314A kernel compiled with the 315.Dv DIAGNOSTIC 316configuration option attempts to detect memory corruption caused by 317such things as writing outside the allocated area and unbalanced calls to the 318.Fn malloc 319and 320.Fn free 321functions. 322Failing consistency checks will cause a panic or a system console message: 323.Bl -bullet -offset indent -compact 324.Pp 325.It 326panic: 327.Dq malloc - bogus type 328.It 329panic: 330.Dq malloc: out of space in kmem_map 331.It 332panic: 333.Dq malloc: allocation too large 334.It 335panic: 336.Dq malloc: wrong bucket 337.It 338panic: 339.Dq malloc: lost data 340.It 341panic: 342.Dq free: unaligned addr 343.It 344panic: 345.Dq free: duplicated free 346.It 347panic: 348.Dq free: multiple frees 349.It 350panic: 351.Dq kmeminit: minbucket too small/struct freelist too big 352.It 353.Dq multiply freed item Aq addr 354.It 355.Dq Data modified on freelist: Aq data object description 356.El 357.Sh DEBUGGING 358A kernel compiled with the 359.Cm MALLOC_DEBUG 360option allows for more extensive debugging of memory allocations. 361The 362.Va debug_malloc_type , 363.Va debug_malloc_size , 364.Va debug_malloc_size_lo 365and 366.Va debug_malloc_size_hi 367variables choose which allocation to debug. 368.Va debug_malloc_type 369should be set to the memory type and 370.Va debug_malloc_size 371should be set to the memory size to debug. 3720 can be used as a wildcard. 373.Va debug_malloc_size_lo 374and 375.Va debug_malloc_size_hi 376can be used to specify a range of sizes if the exact size to debug is not 377known. 378When those are used, 379.Va debug_malloc_size 380needs to be set to the wildcard. 381.Dv M_DEBUG 382can also be specified as an allocation type to force allocation with 383debugging. 384.Pp 385Every call to 386.Fn malloc 387with a memory type and size that matches the debugged type and size will 388allocate two virtual pages. 389The pointer returned will be aligned so that 390the requested area will end at the page boundary and the second virtual page 391will be left unmapped. 392This way we can catch reads and writes outside the allocated area. 393.Pp 394Every call to 395.Fn free 396with memory that was returned by the debugging malloc will cause the memory 397area to become unmapped so that we can catch dangling reads and writes to 398freed memory. 399.Pp 400There are no special diagnostics if any errors are caught by the debugging 401malloc. 402The errors will look like normal access to unmapped memory. 403On a memory access error, the 404.Ic show malloc 405command in 406.Xr ddb 4 407can be invoked to see what memory areas are allocated and freed. 408If the faulting address is within two pages from an address on the allocated 409list, there was an access outside the allocated area. 410If the faulting address is within two pages from an address on the free list, 411there was an access to freed memory. 412.Pp 413Care needs to be taken when using the 414.Cm MALLOC_DEBUG 415option: the memory consumption can run away pretty quickly and there is 416a severe performance degradation when allocating and freeing debugged memory 417types. 418.Sh SEE ALSO 419.Xr vmstat 8 420