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