1.\" $OpenBSD: malloc.9,v 1.65 2017/11/27 09:23:44 mpi 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 27 2017 $ 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_PCB 156Protocol control blocks. 157.It Dv M_RTABLE 158Routing tables. 159.It Dv M_IFADDR 160Interface addresses. 161.It Dv M_SOOPTS 162Socket options. 163.It Dv M_SYSCTL 164Sysctl persistent buffers. 165.It Dv M_COUNTERS 166Per-CPU Counters for use via 167.Xr counters_alloc 9 . 168.It Dv M_IOCTLOPS 169Ioctl data buffers. 170.It Dv M_IOV 171Large IOVs. 172.It Dv M_MOUNT 173VFS mount structs. 174.It Dv M_NFSREQ 175NFS request headers. 176.It Dv M_NFSMNT 177NFS mount structures. 178.It Dv M_VNODE 179Dynamically allocated vnodes. 180.It Dv M_CACHE 181Dynamically allocated cache entries. 182.It Dv M_DQUOT 183UFS quota entries. 184.It Dv M_UFSMNT 185UFS mount structures. 186.It Dv M_SHM 187SVID compatible shared memory segments. 188.It Dv M_VMMAP 189VM map structures. 190.It Dv M_SEM 191SVID compatible semaphores. 192.It Dv M_DIRHASH 193UFS directory hash structures. 194.It Dv M_ACPI 195ACPI structures. 196.It Dv M_VMPMAP 197VM pmap data. 198.It Dv M_FILE 199Open file structures. 200.It Dv M_FILEDESC 201Open file descriptor tables. 202.It Dv M_PROC 203Proc structures. 204.It Dv M_SUBPROC 205Proc sub-structures. 206.It Dv M_VCLUSTER 207Cluster for VFS. 208.It Dv M_MFSNODE 209MFS vnode private part. 210.It Dv M_NETADDR 211Export host address structures. 212.It Dv M_NFSSVC 213NFS server structures. 214.It Dv M_NFSD 215NFS server daemon structures. 216.It Dv M_IPMOPTS 217Internet multicast options. 218.It Dv M_IPMADDR 219Internet multicast addresses. 220.It Dv M_IFMADDR 221Link-level multicast addresses. 222.It Dv M_MRTABLE 223Multicast routing tables. 224.It Dv M_ISOFSMNT 225ISOFS mount structures. 226.It Dv M_ISOFSNODE 227ISOFS vnode private part. 228.It Dv M_MSDOSFSMNT 229MSDOS FS mount structures. 230.It Dv M_MSDOSFSFAT 231MSDOS FS FAT tables. 232.It Dv M_MSDOSFSNODE 233MSDOS FS vnode private part. 234.It Dv M_TTYS 235Allocated tty structures. 236.It Dv M_EXEC 237Argument lists & other mem used by exec. 238.It Dv M_MISCFSMNT 239Miscellaneous FS mount structures. 240.It Dv M_FUSEFS 241FUSE FS mount structures. 242.It Dv M_PFKEY 243Pfkey data. 244.It Dv M_TDB 245Transforms database. 246.It Dv M_XDATA 247IPsec data. 248.It Dv M_PAGEDEP 249File page dependencies. 250.It Dv M_INODEDEP 251Inode dependencies. 252.It Dv M_NEWBLK 253New block allocation. 254.It Dv M_INDIRDEP 255Indirect block dependencies. 256.It Dv M_VMSWAP 257VM swap structures. 258.It Dv M_UVMAMAP 259UVM amap and related. 260.It Dv M_UVMAOBJ 261UVM aobj and related. 262.It Dv M_USB 263USB general. 264.It Dv M_USBDEV 265USB device driver. 266.It Dv M_USBHC 267USB host controller. 268.It Dv M_MEMDESC 269Memory range. 270.It Dv M_CRYPTO_DATA 271.Xr crypto 9 272data buffers. 273.It Dv M_CREDENTIALS 274.Xr ipsec 4 275related credentials. 276.It Dv M_EMULDATA 277Per process emulation data. 278.It Dv M_IP6OPT 279IPv6 options. 280.It Dv M_IP6NDP 281IPv6 neighbour discovery structures. 282.It Dv M_TEMP 283Miscellaneous temporary data buffers. 284.It Dv M_NTFSMNT 285NTFS mount structures. 286.It Dv M_NTFSNTNODE 287NTFS ntnode information. 288.It Dv M_NTFSNODE 289NTFS fnode information. 290.It Dv M_NTFSDIR 291NTFS directory buffers. 292.It Dv M_NTFSHASH 293NTFS ntnode hash tables. 294.It Dv M_NTFSVATTR 295NTFS file attribute information. 296.It Dv M_NTFSRDATA 297NTFS resident data. 298.It Dv M_NTFSDECOMP 299NTFS decompression temporary storage. 300.It Dv M_NTFSRUN 301NTFS vrun storage. 302.It Dv M_KEVENT 303.Xr kqueue 2 304data structures. 305.It Dv M_UDFMOUNT 306UDF mount structures. 307.It Dv M_UDFFENTRY 308UDF file entries. 309.It Dv M_UDFFID 310UDF file ID. 311.It Dv M_AGP 312AGP memory. 313.It Dv M_DRM 314Direct Rendering Manager. 315.El 316.Sh CONTEXT 317.Fn malloc 318and 319.Fn mallocarray 320can be called during autoconf, from process context, or from interrupt context 321if 322.Dv M_NOWAIT 323is passed via 324.Fa flags . 325They can't be called from interrupt context if 326.Dv M_WAITOK 327is passed via 328.Fa flags . 329.Pp 330.Fn free 331can be called during autoconf, from process context, or from interrupt context. 332.Sh RETURN VALUES 333.Fn malloc 334and 335.Fn mallocarray 336return a kernel virtual address that is suitably aligned for storage of 337any type of object. 338.Sh DIAGNOSTICS 339A kernel compiled with the 340.Dv DIAGNOSTIC 341configuration option attempts to detect memory corruption caused by 342such things as writing outside the allocated area and unbalanced calls to 343.Fn malloc 344or 345.Fn mallocarray , 346and 347.Fn free . 348Failing consistency checks will cause a panic or a system console message: 349.Pp 350.Bl -bullet -offset indent -compact 351.It 352panic: 353.Dq malloc: bogus type 354.It 355panic: 356.Dq malloc: out of space in kmem_map 357.It 358panic: 359.Dq malloc: allocation too large 360.It 361panic: 362.Dq malloc: wrong bucket 363.It 364panic: 365.Dq malloc: lost data 366.It 367panic: 368.Dq mallocarray: overflow 369.It 370panic: 371.Dq free: unaligned addr 372.It 373panic: 374.Dq free: duplicated free 375.It 376panic: 377.Dq free: multiple frees 378.It 379panic: 380.Dq free: non-malloced addr 381.It 382panic: 383.Dq free: size too large 384.It 385panic: 386.Dq free: size too small 387.It 388panic: 389.Dq kmeminit: minbucket too small/struct freelist too big 390.It 391.Dq multiply freed item Aq addr 392.It 393.Dq Data modified on freelist: Aq data object description 394.El 395.Sh SEE ALSO 396.Xr systat 1 , 397.Xr vmstat 8 398