1.\" $NetBSD: malloc.9,v 1.6 1997/11/11 10:07:15 mrg 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 Jun 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_DIROFF 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_TEMP 269Misc temporary data buffers. 270.El 271.Pp 272Statistics based on the 273.Fa type 274argument is maintained only if the kernel option 275.Dv KMEMSTATS 276is used when compiling the kernel 277.Po the default in current 278.Nx 279kernels 280.Pc 281and can be examined by using 282.Sq vmstat -m . 283.Sh RETURN VALUES 284.Fn malloc 285returns a kernel virtual address that is suitably aligned for storage of 286any type of object. 287.Sh SEE ALSO 288.Xr vmstat 8 289.Sh DIAGNOSTICS 290A kernel compiled with the 291.Dv DIAGNOSTIC 292configuration option attempts to detect detect memory corruption caused by 293such things as writing outside the allocated area and imbalanced calls to the 294.Fn malloc 295and 296.Fn free 297functions. Failing consistency checks will cause a panic or a system console 298message: 299.Bl -bullet -offset indent -compact 300.Pp 301.It 302panic: 303.Dq malloc - bogus type 304.It 305panic: 306.Dq malloc: out of space in kmem_map 307.It 308panic: 309.Dq malloc: allocation too large 310.It 311panic: 312.Dq malloc: wrong bucket 313.It 314panic: 315.Dq malloc: lost data 316.It 317panic: 318.Dq free: unaligned addr 319.It 320panic: 321.Dq free: duplicated free 322.It 323panic: 324.Dq free: multiple frees 325.It 326panic: 327.Dq init: minbucket too small/struct freelist too big 328.It 329.Dq multiply freed item Aq addr 330.It 331.Dq Data modified on freelist: Aq data object description 332.El 333