1.\" $NetBSD: malloc.9,v 1.15 2001/05/06 23:48:33 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 characteristics 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_TEMP 278Misc temporary data buffers. 279.It Dv M_DMAMAP 280.Xr bus_dma 9 281structures. 282.It Dv M_IPFLOW 283IP flow entries. 284.It Dv M_USB 285USB general. 286.It Dv M_USBDEV 287USB permanent. 288.It Dv M_POOL 289Memory 290.Xr pool 9 291structures. 292.It Dv M_CODA 293Coda file system structures and tables. 294.It Dv M_FILECOREMNT 295Filecore FS mount structures. 296.It Dv M_FILECORENODE 297Filecore FS vnode private part. 298.It Dv M_RAIDFRAME 299RAIDframe structures and IO buffers. 300.It Dv M_USBHC 301USB host controller. 302.It Dv M_SECA 303security associations, key management. 304.It Dv M_IP6OPT 305IPv6 options. 306.It Dv M_IP6NDP 307IPv6 Neighbour Discovery. 308.It Dv M_NTFS 309Windows NT file system structures. 310.It Dv M_PAGEDEP 311File page dependencies. 312.It Dv M_INODEDEP 313Inode dependencies. 314.It Dv M_NEWBLK 315New block allocation. 316.It Dv M_BMSAFEMAP 317Block or frag allocated from cyl group map. 318.It Dv M_ALLOCDIRECT 319Block or frag dependency for an inode. 320.It Dv M_INDIRDEP 321Indirect block dependencies. 322.It Dv M_ALLOCINDIR 323Block dependency for an indirect block. 324.It Dv M_FREEFRAG 325Previously used frag for an inode. 326.It Dv M_FREEBLKS 327Blocks freed from an inode. 328.It Dv M_FREEFILE 329Inode deallocated. 330.It Dv M_DIRADD 331New directory entry. 332.It Dv M_MKDIR 333New directory. 334.It Dv M_DIRREM 335Directory entry deleted. 336.It Dv M_IP6RR 337IPv6 Router Renumbering Prefix. 338.It Dv M_RR_ADDR 339IPv6 Router Renumbering Ifid. 340.It Dv M_SOFTINTR 341Softinterrupt structures. 342.It Dv M_EMULDATA 343Per-process emulation data. 344.It Dv M_1394CTL 345IEEE 1394 control structures. 346.It Dv M_1394DATA 347IEEE 1394 data buffers. 348.El 349.Pp 350Statistics based on the 351.Fa type 352argument is maintained only if the kernel option 353.Dv KMEMSTATS 354is used when compiling the kernel 355.Po 356the default in current 357.Nx 358kernels 359.Pc 360and can be examined by using 361.Sq vmstat -m . 362.Sh RETURN VALUES 363.Fn malloc 364returns a kernel virtual address that is suitably aligned for storage of 365any type of object. 366.Sh SEE ALSO 367.Xr vmstat 1 368.Sh DIAGNOSTICS 369A kernel compiled with the 370.Dv DIAGNOSTIC 371configuration option attempts to detect memory corruption caused by 372such things as writing outside the allocated area and imbalanced calls to the 373.Fn malloc 374and 375.Fn free 376functions. 377Failing consistency checks will cause a panic or a system console message: 378.Bl -bullet -offset indent -compact 379.Pp 380.It 381panic: 382.Dq malloc - bogus type 383.It 384panic: 385.Dq malloc: out of space in kmem_map 386.It 387panic: 388.Dq malloc: allocation too large 389.It 390panic: 391.Dq malloc: wrong bucket 392.It 393panic: 394.Dq malloc: lost data 395.It 396panic: 397.Dq free: unaligned addr 398.It 399panic: 400.Dq free: duplicated free 401.It 402panic: 403.Dq free: multiple frees 404.It 405panic: 406.Dq init: minbucket too small/struct freelist too big 407.It 408.Dq multiply freed item Aq addr 409.It 410.Dq Data modified on freelist: Aq data object description 411.El 412