1.\" $OpenBSD: malloc.9,v 1.60 2014/11/02 05:16:43 tedu 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.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 22.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 23.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd $Mdocdate: November 2 2014 $ 32.Dt MALLOC 9 33.Os 34.Sh NAME 35.Nm malloc , 36.Nm mallocarray , 37.Nm free 38.Nd kernel memory allocator 39.Sh SYNOPSIS 40.In sys/types.h 41.In sys/malloc.h 42.Ft void * 43.Fn malloc "size_t size" "int type" "int flags" 44.Ft void * 45.Fn mallocarray "size_t nmemb" "size_t size" "int type" "int flags" 46.Ft void 47.Fn free "void *addr" "int type" "size_t size" 48.Sh DESCRIPTION 49The 50.Fn malloc 51function allocates uninitialized memory in kernel address space for an 52object whose size is specified by 53.Fa size . 54.Pp 55The 56.Fn mallocarray 57function is the same as 58.Fn malloc , 59but allocates space for an array of 60.Fa nmemb 61objects and checks for arithmetic overflow. 62.Pp 63The 64.Fn free 65function releases memory at address 66.Fa addr 67that was previously allocated by 68.Fn malloc 69or 70.Fn mallocarray 71for re-use. 72The same object size originally provided to 73.Fn malloc 74should be specified by 75.Fa size . 76If 77.Fa addr 78is a null pointer, no action occurs. 79.Pp 80The 81.Fa flags 82argument affects the operational characteristics of 83.Fn malloc 84and 85.Fn mallocarray 86as follows: 87.Bl -tag -width xxx -offset indent 88.It Dv M_WAITOK 89If memory is currently unavailable, 90.Fn malloc 91may call sleep to wait for resources to be released by other processes. 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. 98.It Dv M_CANFAIL 99In the 100.Dv M_WAITOK 101case, if not enough memory is available, return 102.Dv NULL 103instead of calling 104.Xr panic 9 . 105If 106.Fn mallocarray 107detects an overflow 108or 109.Fn malloc 110detects an excessive allocation, return 111.Dv NULL 112instead of calling 113.Xr panic 9 . 114.It Dv M_ZERO 115Causes allocated memory to be zeroed. 116.El 117.Pp 118One of 119.Dv M_NOWAIT 120or 121.Dv M_WAITOK 122must be specified via the 123.Fa flags 124argument. 125.Pp 126The 127.Fa type 128argument broadly identifies the kernel subsystem for which the allocated 129memory was needed, and is commonly used to maintain statistics about 130kernel memory usage. 131These statistics can be examined using 132.Xr vmstat 8 133or 134.Xr systat 1 135if either of the kernel 136.Xr options 4 137.Cm KMEMSTATS 138or 139.Cm DEBUG 140are enabled. 141.Pp 142The following types are currently defined: 143.Pp 144.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 145.It Dv M_FREE 146Should be on free list. 147.It Dv M_DEVBUF 148Device driver memory. 149.It Dv M_DEBUG 150.Nm malloc 151debug structures. 152.It Dv M_PCB 153Protocol control blocks. 154.It Dv M_RTABLE 155Routing tables. 156.It Dv M_FTABLE 157Fragment reassembly headers. 158.It Dv M_IFADDR 159Interface addresses. 160.It Dv M_SOOPTS 161Socket options. 162.It Dv M_SYSCTL 163Sysctl persistent buffers. 164.It Dv M_IOCTLOPS 165Ioctl data buffers. 166.It Dv M_IOV 167Large IOVs. 168.It Dv M_MOUNT 169VFS mount structs. 170.It Dv M_NFSREQ 171NFS request headers. 172.It Dv M_NFSMNT 173NFS mount structures. 174.It Dv M_VNODE 175Dynamically allocated vnodes. 176.It Dv M_CACHE 177Dynamically allocated cache entries. 178.It Dv M_DQUOT 179UFS quota entries. 180.It Dv M_UFSMNT 181UFS mount structures. 182.It Dv M_SHM 183SVID compatible shared memory segments. 184.It Dv M_VMMAP 185VM map structures. 186.It Dv M_SEM 187SVID compatible semaphores. 188.It Dv M_DIRHASH 189UFS directory hash structures. 190.It Dv M_ACPI 191ACPI structures. 192.It Dv M_VMPMAP 193VM pmap data. 194.It Dv M_FILE 195Open file structures. 196.It Dv M_FILEDESC 197Open file descriptor tables. 198.It Dv M_PROC 199Proc structures. 200.It Dv M_SUBPROC 201Proc sub-structures. 202.It Dv M_VCLUSTER 203Cluster for VFS. 204.It Dv M_MFSNODE 205MFS vnode private part. 206.It Dv M_NETADDR 207Export host address structures. 208.It Dv M_NFSSVC 209NFS server structures. 210.It Dv M_NFSD 211NFS server daemon structures. 212.It Dv M_IPMOPTS 213Internet multicast options. 214.It Dv M_IPMADDR 215Internet multicast addresses. 216.It Dv M_IFMADDR 217Link-level multicast addresses. 218.It Dv M_MRTABLE 219Multicast routing tables. 220.It Dv M_ISOFSMNT 221ISOFS mount structures. 222.It Dv M_ISOFSNODE 223ISOFS vnode private part. 224.It Dv M_MSDOSFSMNT 225MSDOS FS mount structures. 226.It Dv M_MSDOSFSFAT 227MSDOS FS FAT tables. 228.It Dv M_MSDOSFSNODE 229MSDOS FS vnode private part. 230.It Dv M_TTYS 231Allocated tty structures. 232.It Dv M_EXEC 233Argument lists & other mem used by exec. 234.It Dv M_MISCFSMNT 235Miscellaneous FS mount structures. 236.It Dv M_FUSEFS 237FUSE FS mount structures. 238.It Dv M_PFKEY 239Pfkey data. 240.It Dv M_TDB 241Transforms database. 242.It Dv M_XDATA 243IPsec data. 244.It Dv M_PAGEDEP 245File page dependencies. 246.It Dv M_INODEDEP 247Inode dependencies. 248.It Dv M_NEWBLK 249New block allocation. 250.It Dv M_INDIRDEP 251Indirect block dependencies. 252.It Dv M_VMSWAP 253VM swap structures. 254.It Dv M_UVMAMAP 255UVM amap and related. 256.It Dv M_UVMAOBJ 257UVM aobj and related. 258.It Dv M_USB 259USB general. 260.It Dv M_USBDEV 261USB device driver. 262.It Dv M_USBHC 263USB host controller. 264.It Dv M_MEMDESC 265Memory range. 266.It Dv M_CRYPTO_DATA 267.Xr crypto 9 268data buffers. 269.It Dv M_CREDENTIALS 270.Xr ipsec 4 271related credentials. 272.It Dv M_EMULDATA 273Per process emulation data. 274.It Dv M_IP6OPT 275IPv6 options. 276.It Dv M_IP6NDP 277IPv6 neighbour discovery structures. 278.It Dv M_TEMP 279Miscellaneous temporary data buffers. 280.It Dv M_NTFSMNT 281NTFS mount structures. 282.It Dv M_NTFSNTNODE 283NTFS ntnode information. 284.It Dv M_NTFSNODE 285NTFS fnode information. 286.It Dv M_NTFSDIR 287NTFS directory buffers. 288.It Dv M_NTFSHASH 289NTFS ntnode hash tables. 290.It Dv M_NTFSVATTR 291NTFS file attribute information. 292.It Dv M_NTFSRDATA 293NTFS resident data. 294.It Dv M_NTFSDECOMP 295NTFS decompression temporary storage. 296.It Dv M_NTFSRUN 297NTFS vrun storage. 298.It Dv M_KEVENT 299.Xr kqueue 2 300data structures. 301.It Dv M_BWMETER 302Multicast upcall bandwidth meters. 303.It Dv M_UDFMOUNT 304UDF mount structures. 305.It Dv M_UDFFENTRY 306UDF file entries. 307.It Dv M_UDFFID 308UDF file ID. 309.It Dv M_AGP 310AGP memory. 311.It Dv M_DRM 312Direct Rendering Manager. 313.El 314.Sh CONTEXT 315.Fn malloc 316and 317.Fn mallocarray 318can be called during autoconf, from process context, or from interrupt context 319if 320.Dv M_NOWAIT 321is passed via 322.Fa flags . 323They can't be called from interrupt context if 324.Dv M_WAITOK 325is passed via 326.Fa flags . 327.Pp 328.Fn free 329can be called during autoconf, from process context, or from interrupt context. 330.Sh RETURN VALUES 331.Fn malloc 332and 333.Fn mallocarray 334return a kernel virtual address that is suitably aligned for storage of 335any type of object. 336.Sh DIAGNOSTICS 337A kernel compiled with the 338.Dv DIAGNOSTIC 339configuration option attempts to detect memory corruption caused by 340such things as writing outside the allocated area and unbalanced calls to 341.Fn malloc 342or 343.Fn mallocarray , 344and 345.Fn free . 346Failing consistency checks will cause a panic or a system console message: 347.Pp 348.Bl -bullet -offset indent -compact 349.It 350panic: 351.Dq malloc: bogus type 352.It 353panic: 354.Dq malloc: out of space in kmem_map 355.It 356panic: 357.Dq malloc: allocation too large 358.It 359panic: 360.Dq malloc: wrong bucket 361.It 362panic: 363.Dq malloc: lost data 364.It 365panic: 366.Dq mallocarray: overflow 367.It 368panic: 369.Dq free: unaligned addr 370.It 371panic: 372.Dq free: duplicated free 373.It 374panic: 375.Dq free: multiple frees 376.It 377panic: 378.Dq free: non-malloced addr 379.It 380panic: 381.Dq free: size too large 382.It 383panic: 384.Dq free: size too small 385.It 386panic: 387.Dq kmeminit: minbucket too small/struct freelist too big 388.It 389.Dq multiply freed item Aq addr 390.It 391.Dq Data modified on freelist: Aq data object description 392.El 393.Sh DEBUGGING 394A kernel compiled with the 395.Cm MALLOC_DEBUG 396option allows for more extensive debugging of memory allocations. 397The 398.Va debug_malloc_type , 399.Va debug_malloc_size , 400.Va debug_malloc_size_lo 401and 402.Va debug_malloc_size_hi 403variables choose which allocation to debug. 404.Va debug_malloc_type 405should be set to the memory type and 406.Va debug_malloc_size 407should be set to the memory size to debug. 4080 can be used as a wildcard. 409.Va debug_malloc_size_lo 410and 411.Va debug_malloc_size_hi 412can be used to specify a range of sizes if the exact size to debug is not 413known. 414When those are used, 415.Va debug_malloc_size 416needs to be set to the wildcard. 417.Dv M_DEBUG 418can also be specified as an allocation type to force allocation with 419debugging. 420.Pp 421Every call to 422.Fn malloc 423or 424.Fn mallocarray 425with a memory type and size that matches the debugged type and size will 426allocate two virtual pages. 427The pointer returned will be aligned so that 428the requested area will end at the page boundary and the second virtual page 429will be left unmapped. 430This way we can catch reads and writes outside the allocated area. 431.Pp 432Every call to 433.Fn free 434with memory that was returned by the debugging allocators will cause the memory 435area to become unmapped so that we can catch dangling reads and writes to 436freed memory. 437.Pp 438There are no special diagnostics if any errors are caught by the debugging 439malloc. 440The errors will look like normal access to unmapped memory. 441On a memory access error, the 442.Ic show malloc 443command in 444.Xr ddb 4 445can be invoked to see what memory areas are allocated and freed. 446If the faulting address is within two pages from an address on the allocated 447list, there was an access outside the allocated area. 448If the faulting address is within two pages from an address on the free list, 449there was an access to freed memory. 450.Pp 451Care needs to be taken when using the 452.Cm MALLOC_DEBUG 453option: the memory consumption can run away pretty quickly and there is 454a severe performance degradation when allocating and freeing debugged memory 455types. 456.Sh SEE ALSO 457.Xr systat 1 , 458.Xr vmstat 8 459