1.\" $NetBSD: malloc.9,v 1.13 2000/12/24 02:52:53 wiz Exp $ 2.\" 3.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd June 16, 1996 38.Dt MALLOC 9 39.Os 40.Sh NAME 41.Nm malloc , 42.Nm free 43.Nd kernel memory allocator 44.Sh SYNOPSIS 45.Ft void * 46.Fn malloc "unsigned long size" "int type" "int flags" 47.Fn MALLOC "space" "cast" "unsigned long size" "int type" "int flags" 48.Ft void 49.Fn free "void *addr" "int type" 50.Fn FREE "void *addr" "int type" 51.Sh DESCRIPTION 52The 53.Fn malloc 54function allocates uninitialized memory in kernel address space for an 55object whose size is specified by 56.Fa size . 57.Fn free 58releases memory at address 59.Fa addr 60that was previously allocated by 61.Fn malloc 62for re-use. 63The 64.Fn MALLOC 65macro variant is functionally equivalent to 66.Bd -literal -offset indent 67(space) = (cast)malloc((u_long)(size), type, flags) 68.Ed 69.Pp 70and the 71.Fn FREE 72macro variant is equivalent to 73.Bd -literal -offset indent 74free((caddr_t)(addr), type) 75.Ed 76.Pp 77Unlike its standard C library counterpart 78.Pq Xr malloc 3 , 79the kernel version takes two more arguments. The 80.Fa flags 81argument further qualifies 82.Fn malloc No Ns 's 83operational charateristics as follows: 84.Bl -tag -offset indent 85.It Dv M_NOWAIT 86Causes 87.Fn malloc 88to return 89.Dv NULL 90if the request cannot be immediately fulfilled due to resource shortage. 91Otherwise, 92.Fn malloc 93may call sleep to wait for resources to be released by other processes. 94If this flag is not set, 95.Fn malloc 96will never return 97.Dv NULL . 98Note that 99.Dv M_WAITOK 100is conveniently defined to be 0, and hence maybe or'ed into the 101.Fa flags 102argument to indicate that it's Ok to wait for resources. 103.El 104.Pp 105Currently, only one flag is defined. 106.Pp 107The 108.Fa type 109argument broadly identifies the kernel subsystem for which the allocated 110memory was needed, and is commonly used to maintain statistics about 111kernel memory usage. 112The following types are currently defined: 113.Pp 114.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 115.It Dv M_FREE 116Should be on free list. 117.It Dv M_MBUF 118Mbuf memory. 119.It Dv M_DEVBUF 120Device driver memory. 121.It Dv M_SOCKET 122Socket structure. 123.It Dv M_PCB 124Protocol control block. 125.It Dv M_RTABLE 126Routing tables. 127.It Dv M_HTABLE 128IMP host tables. 129.It Dv M_FTABLE 130Fragment reassembly header. 131.It Dv M_ZOMBIE 132Zombie proc status 133.It Dv M_IFADDR 134Interface address. 135.It Dv M_SOOPTS 136Socket options. 137.It Dv M_SONAME 138Socket name. 139.It Dv M_NAMEI 140Namei path name buffer. 141.It Dv M_GPROF 142Kernel profiling buffer. 143.It Dv M_IOCTLOPS 144Ioctl data buffer. 145.It Dv M_MAPMEM 146Mapped memory descriptors. 147.It Dv M_CRED 148Credentials. 149.It Dv M_PGRP 150Process group header. 151.It Dv M_SESSION 152Session header. 153.It Dv M_IOV 154Large iov's. 155.It Dv M_MOUNT 156Vfs mount struct. 157.It Dv M_FHANDLE 158Network file handle. 159.It Dv M_NFSREQ 160NFS request header. 161.It Dv M_NFSMNT 162NFS mount structure. 163.It Dv M_NFSNODE 164NFS vnode private part. 165.It Dv M_VNODE 166Dynamically allocated vnodes. 167.It Dv M_CACHE 168Dynamically allocated cache entries. 169.It Dv M_DQUOT 170UFS quota entries. 171.It Dv M_UFSMNT 172UFS mount structure. 173.It Dv M_SHM 174SVID compatible shared memory segments. 175.It Dv M_VMMAP 176VM map structures. 177.It Dv M_VMMAPENT 178VM map entry structures. 179.It Dv M_VMOBJ 180VM object structure. 181.It Dv M_VMOBJHASH 182VM object hash structure. 183.It Dv M_VMPMAP 184VM pmap. 185.It Dv M_VMPVENT 186VM phys-virt mapping entry. 187.It Dv M_VMPAGER 188XXX: VM pager struct. 189.It Dv M_VMPGDATA 190XXX: VM pager private data. 191.It Dv M_FILE 192Open file structure. 193.It Dv M_FILEDESC 194Open file descriptor table. 195.It Dv M_LOCKF 196Byte-range locking structures. 197.It Dv M_PROC 198Proc structures. 199.It Dv M_SUBPROC 200Proc sub-structures. 201.It Dv M_SEGMENT 202Segment for LFS. 203.It Dv M_LFSNODE 204LFS vnode private part. 205.It Dv M_FFSNODE 206FFS vnode private part. 207.It Dv M_MFSNODE 208MFS vnode private part. 209.It Dv M_NQLEASE 210Nqnfs lease. 211.It Dv M_NQMHOST 212Nqnfs host address table. 213.It Dv M_NETADDR 214Export host address structure. 215.It Dv M_NFSSVC 216Nfs server structure. 217.It Dv M_NFSUID 218Nfs uid mapping structure. 219.It Dv M_NFSD 220Nfs server daemon structure. 221.It Dv M_IPMOPTS 222Internet multicast options. 223.It Dv M_IPMADDR 224Internet multicast address. 225.It Dv M_IFMADDR 226Link-level multicast address. 227.It Dv M_MRTABLE 228Multicast routing tables. 229.It Dv M_ISOFSMNT 230ISOFS mount structure. 231.It Dv M_ISOFSNODE 232ISOFS vnode private part. 233.It Dv M_MSDOSFSMNT 234MSDOS FS mount structure. 235.It Dv M_MSDOSFSFAT 236MSDOS FS fat table. 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 244Miscfs mount structures. 245.It Dv M_MISCFSNODE 246Miscfs vnode private part. 247.It Dv M_ADOSFSMNT 248Adosfs mount structures. 249.It Dv M_ADOSFSNODE 250Adosfs vnode private part. 251.It Dv M_ANODE 252Adosfs anode structures and tables. 253.It Dv M_IPQ 254IP packet queue entry. 255.It Dv M_AFS 256Andrew File System. 257.It Dv M_ADOSFSBITMAP 258Adosfs bitmap. 259.It Dv M_NFSSRVDESC 260NFS server descriptor. 261.It Dv M_NFSDIROFF 262NFS directory cookies. 263.It Dv M_NFSBIGFH 264NFS big filehandle. 265.It Dv M_EXT2FSNODE 266EXT2FS vnode private part. 267.It Dv M_VMSWAP 268VM swap structures. 269.It Dv M_VMPAGE 270VM page structures. 271.It Dv M_VMPBUCKET 272VM page buckets. 273.It Dv M_UVMAMAP 274UVM amap and related structs. 275.It Dv M_UVMAOBJ 276UVM aobj and related structs. 277.It Dv M_DMAMAP 278.Xr bus_dma 9 279structures. 280.It Dv M_IPFLOW 281IP flow entries. 282.It Dv M_USB 283USB general. 284.It Dv M_USBDEV 285USB permanent. 286.It Dv M_POOL 287Memory 288.Xr pool 9 289structures. 290.It Dv M_CFS 291Coda file system structures and tables. 292.It Dv M_TEMP 293Misc temporary data buffers. 294.It Dv M_RAIDFRAME 295RAIDframe structures and IO buffers. 296.El 297.Pp 298Statistics based on the 299.Fa type 300argument is maintained only if the kernel option 301.Dv KMEMSTATS 302is used when compiling the kernel 303.Po 304the default in current 305.Nx 306kernels 307.Pc 308and can be examined by using 309.Sq vmstat -m . 310.Sh RETURN VALUES 311.Fn malloc 312returns a kernel virtual address that is suitably aligned for storage of 313any type of object. 314.Sh SEE ALSO 315.Xr vmstat 8 316.Sh DIAGNOSTICS 317A kernel compiled with the 318.Dv DIAGNOSTIC 319configuration option attempts to detect memory corruption caused by 320such things as writing outside the allocated area and imbalanced calls to the 321.Fn malloc 322and 323.Fn free 324functions. 325Failing consistency checks will cause a panic or a system console message: 326.Bl -bullet -offset indent -compact 327.Pp 328.It 329panic: 330.Dq malloc - bogus type 331.It 332panic: 333.Dq malloc: out of space in kmem_map 334.It 335panic: 336.Dq malloc: allocation too large 337.It 338panic: 339.Dq malloc: wrong bucket 340.It 341panic: 342.Dq malloc: lost data 343.It 344panic: 345.Dq free: unaligned addr 346.It 347panic: 348.Dq free: duplicated free 349.It 350panic: 351.Dq free: multiple frees 352.It 353panic: 354.Dq init: minbucket too small/struct freelist too big 355.It 356.Dq multiply freed item Aq addr 357.It 358.Dq Data modified on freelist: Aq data object description 359.El 360