1.\" $NetBSD: malloc.9,v 1.8 1998/07/29 22:07:14 pk 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 NetBSD 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. The following types are currently defined: 112.Pp 113.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 114.It Dv M_FREE 115Should be on free list. 116.It Dv M_MBUF 117Mbuf memory. 118.It Dv M_DEVBUF 119Device driver memory. 120.It Dv M_SOCKET 121Socket structure. 122.It Dv M_PCB 123Protocol control block. 124.It Dv M_RTABLE 125Routing tables. 126.It Dv M_HTABLE 127IMP host tables. 128.It Dv M_FTABLE 129Fragment reassembly header. 130.It Dv M_ZOMBIE 131Zombie proc status 132.It Dv M_IFADDR 133Interface address. 134.It Dv M_SOOPTS 135Socket options. 136.It Dv M_SONAME 137Socket name. 138.It Dv M_NAMEI 139Namei path name buffer. 140.It Dv M_GPROF 141Kernel profiling buffer. 142.It Dv M_IOCTLOPS 143Ioctl data buffer. 144.It Dv M_MAPMEM 145Mapped memory descriptors. 146.It Dv M_CRED 147Credentials. 148.It Dv M_PGRP 149Process group header. 150.It Dv M_SESSION 151Session header. 152.It Dv M_IOV 153Large iov's. 154.It Dv M_MOUNT 155Vfs mount struct. 156.It Dv M_FHANDLE 157Network file handle. 158.It Dv M_NFSREQ 159NFS request header. 160.It Dv M_NFSMNT 161NFS mount structure. 162.It Dv M_NFSNODE 163NFS vnode private part. 164.It Dv M_VNODE 165Dynamically allocated vnodes. 166.It Dv M_CACHE 167Dynamically allocated cache entries. 168.It Dv M_DQUOT 169UFS quota entries. 170.It Dv M_UFSMNT 171UFS mount structure. 172.It Dv M_SHM 173SVID compatible shared memory segments. 174.It Dv M_VMMAP 175VM map structures. 176.It Dv M_VMMAPENT 177VM map entry structures. 178.It Dv M_VMOBJ 179VM object structure. 180.It Dv M_VMOBJHASH 181VM object hash structure. 182.It Dv M_VMPMAP 183VM pmap. 184.It Dv M_VMPVENT 185VM phys-virt mapping entry. 186.It Dv M_VMPAGER 187XXX: VM pager struct. 188.It Dv M_VMPGDATA 189XXX: VM pager private data. 190.It Dv M_FILE 191Open file structure. 192.It Dv M_FILEDESC 193Open file descriptor table. 194.It Dv M_LOCKF 195Byte-range locking structures. 196.It Dv M_PROC 197Proc structures. 198.It Dv M_SUBPROC 199Proc sub-structures. 200.It Dv M_SEGMENT 201Segment for LFS. 202.It Dv M_LFSNODE 203LFS vnode private part. 204.It Dv M_FFSNODE 205FFS vnode private part. 206.It Dv M_MFSNODE 207MFS vnode private part. 208.It Dv M_NQLEASE 209Nqnfs lease. 210.It Dv M_NQMHOST 211Nqnfs host address table. 212.It Dv M_NETADDR 213Export host address structure. 214.It Dv M_NFSSVC 215Nfs server structure. 216.It Dv M_NFSUID 217Nfs uid mapping structure. 218.It Dv M_NFSD 219Nfs server daemon structure. 220.It Dv M_IPMOPTS 221Internet multicast options. 222.It Dv M_IPMADDR 223Internet multicast address. 224.It Dv M_IFMADDR 225Link-level multicast address. 226.It Dv M_MRTABLE 227Multicast routing tables. 228.It Dv M_ISOFSMNT 229ISOFS mount structure. 230.It Dv M_ISOFSNODE 231ISOFS vnode private part. 232.It Dv M_MSDOSFSMNT 233MSDOS FS mount structure. 234.It Dv M_MSDOSFSFAT 235MSDOS FS fat table. 236.It Dv M_MSDOSFSNODE 237MSDOS FS vnode private part. 238.It Dv M_TTYS 239Allocated tty structures. 240.It Dv M_EXEC 241Argument lists & other mem used by exec. 242.It Dv M_MISCFSMNT 243Miscfs mount structures. 244.It Dv M_MISCFSNODE 245Miscfs vnode private part. 246.It Dv M_ADOSFSMNT 247Adosfs mount structures. 248.It Dv M_ADOSFSNODE 249Adosfs vnode private part. 250.It Dv M_ANODE 251Adosfs anode structures and tables. 252.It Dv M_IPQ 253IP packet queue entry. 254.It Dv M_AFS 255Andrew File System. 256.It Dv M_ADOSFSBITMAP 257Adosfs bitmap. 258.It Dv M_NFSSRVDESC 259NFS server descriptor. 260.It Dv M_NFSDIROFF 261NFS directory cookies. 262.It Dv M_NFSBIGFH 263NFS big filehandle. 264.It Dv M_EXT2FSNODE 265EXT2FS vnode private part. 266.It Dv M_VMSWAP 267VM swap structures. 268.It Dv M_VMPAGE 269VM page structures. 270.It Dv M_VMPBUCKET 271VM page buckets. 272.It Dv M_UVMAMAP 273UVM amap and related structs. 274.It Dv M_UVMAOBJ 275UVM aobj and related structs. 276.It Dv M_DMAMAP 277.Xr bus_dma 9 278structures. 279.It Dv M_IPFLOW 280IP flow entries. 281.It Dv M_USB 282USB general. 283.It Dv M_USBDEV 284USB permanent. 285.It Dv M_POOL 286Memory 287.Xr pool 9 288structures. 289.It Dv M_CFS 290Coda file system structures and tables. 291.It Dv M_TEMP 292Misc temporary data buffers. 293.El 294.Pp 295Statistics based on the 296.Fa type 297argument is maintained only if the kernel option 298.Dv KMEMSTATS 299is used when compiling the kernel 300.Po the default in current 301.Nx 302kernels 303.Pc 304and can be examined by using 305.Sq vmstat -m . 306.Sh RETURN VALUES 307.Fn malloc 308returns a kernel virtual address that is suitably aligned for storage of 309any type of object. 310.Sh SEE ALSO 311.Xr vmstat 8 312.Sh DIAGNOSTICS 313A kernel compiled with the 314.Dv DIAGNOSTIC 315configuration option attempts to detect detect memory corruption caused by 316such things as writing outside the allocated area and imbalanced calls to the 317.Fn malloc 318and 319.Fn free 320functions. Failing consistency checks will cause a panic or a system console 321message: 322.Bl -bullet -offset indent -compact 323.Pp 324.It 325panic: 326.Dq malloc - bogus type 327.It 328panic: 329.Dq malloc: out of space in kmem_map 330.It 331panic: 332.Dq malloc: allocation too large 333.It 334panic: 335.Dq malloc: wrong bucket 336.It 337panic: 338.Dq malloc: lost data 339.It 340panic: 341.Dq free: unaligned addr 342.It 343panic: 344.Dq free: duplicated free 345.It 346panic: 347.Dq free: multiple frees 348.It 349panic: 350.Dq init: minbucket too small/struct freelist too big 351.It 352.Dq multiply freed item Aq addr 353.It 354.Dq Data modified on freelist: Aq data object description 355.El 356