1.\" $NetBSD: malloc.9,v 1.26 2002/10/14 13:43:26 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 December 4, 2001 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 unsigned long 49.Fn malloc_roundup "unsigned long size" 50.Ft void 51.Fn free "void *addr" "int type" 52.Fn FREE "void *addr" "int type" 53.Sh DESCRIPTION 54The 55.Fn malloc 56function allocates uninitialized memory in kernel address space for an 57object whose size is specified by 58.Fa size . 59.Fn malloc_roundup 60returns the actual size of the allocation unit for the given value. 61.Fn free 62releases memory at address 63.Fa addr 64that was previously allocated by 65.Fn malloc 66for re-use. 67The 68.Fn MALLOC 69macro variant is functionally equivalent to 70.Bd -literal -offset indent 71(space) = (cast)malloc((u_long)(size), type, flags) 72.Ed 73.Pp 74and the 75.Fn FREE 76macro variant is equivalent to 77.Bd -literal -offset indent 78free((caddr_t)(addr), type) 79.Ed 80.Pp 81The 82.Fn MALLOC 83is intended to be used with a compile-time constant 84.Fa size 85so that the compiler can do constant folding. 86.Pp 87Unlike its standard C library counterpart 88.Pq Xr malloc 3 , 89the kernel version takes two more arguments. 90.Pp 91The 92.Fa flags 93argument further qualifies 94.Fn malloc 95operational characteristics as follows: 96.Bl -tag -offset indent -width M_CANFAIL 97.It Dv M_NOWAIT 98Causes 99.Fn malloc 100to return 101.Dv NULL 102if the request cannot be immediately fulfilled due to resource shortage. 103If this flag is not set 104(see 105.Dv M_WAITOK ) , 106.Fn malloc 107will never return 108.Dv NULL . 109.It Dv M_WAITOK 110By default, 111.Fn malloc 112may call 113.Xr sleep 9 114to wait for resources to be released by other processes, and this 115flag represents this behaviour. 116Note that 117.Dv M_WAITOK 118is conveniently defined to be 0, and hence may be or'ed into the 119.Fa flags 120argument to indicate that it's ok to wait for resources. 121.It Dv M_ZERO 122Causes the allocated memory to be set to all zeros. 123.It Dv M_CANFAIL 124Changes behaviour for 125.Dv M_WAITOK 126case - if the requested memory size is bigger than 127.Fn malloc 128can ever allocate, return failure, rather than calling 129.Xr panic 9 . 130This is different to M_NOWAIT, since 131the call can still wait for resources. 132.Pp 133Rather than depending on 134.Dv M_CANFAIL , 135kernel code should do proper bound checking itself. 136This flag should only be used in cases where this is not feasible. 137Since it can hide real kernel bugs, it's usage is 138.Em strongly discouraged . 139.El 140.Pp 141The 142.Fa type 143argument broadly identifies the kernel subsystem for which the allocated 144memory was needed, and is commonly used to maintain statistics about 145kernel memory usage. 146The following types are currently defined: 147.Pp 148.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 149.It Dv M_FREE 150Should be on free list. 151.It Dv M_MBUF 152Mbuf memory. 153.It Dv M_DEVBUF 154Device driver memory. 155.It Dv M_SOCKET 156Socket structure. 157.It Dv M_PCB 158Protocol control block. 159.It Dv M_RTABLE 160Routing tables. 161.It Dv M_HTABLE 162IMP host tables. 163.It Dv M_FTABLE 164Fragment reassembly header. 165.It Dv M_ZOMBIE 166Zombie proc status 167.It Dv M_IFADDR 168Interface address. 169.It Dv M_SOOPTS 170Socket options. 171.It Dv M_SONAME 172Socket name. 173.It Dv M_NAMEI 174Namei path name buffer. 175.It Dv M_GPROF 176Kernel profiling buffer. 177.It Dv M_IOCTLOPS 178Ioctl data buffer. 179.It Dv M_MAPMEM 180Mapped memory descriptors. 181.It Dv M_CRED 182Credentials. 183.It Dv M_PGRP 184Process group header. 185.It Dv M_SESSION 186Session header. 187.It Dv M_IOV 188Large iov's. 189.It Dv M_MOUNT 190Vfs mount struct. 191.It Dv M_FHANDLE 192Network file handle. 193.It Dv M_NFSREQ 194NFS request header. 195.It Dv M_NFSMNT 196NFS mount structure. 197.It Dv M_NFSNODE 198NFS vnode private part. 199.It Dv M_VNODE 200Dynamically allocated vnodes. 201.It Dv M_CACHE 202Dynamically allocated cache entries. 203.It Dv M_DQUOT 204UFS quota entries. 205.It Dv M_UFSMNT 206UFS mount structure. 207.It Dv M_SHM 208SVID compatible shared memory segments. 209.It Dv M_VMMAP 210VM map structures. 211.It Dv M_VMMAPENT 212VM map entry structures. 213.It Dv M_VMOBJ 214VM object structure. 215.It Dv M_VMOBJHASH 216VM object hash structure. 217.It Dv M_VMPMAP 218VM pmap. 219.It Dv M_VMPVENT 220VM phys-virt mapping entry. 221.It Dv M_VMPAGER 222XXX: VM pager struct. 223.It Dv M_VMPGDATA 224XXX: VM pager private data. 225.It Dv M_FILE 226Open file structure. 227.It Dv M_FILEDESC 228Open file descriptor table. 229.It Dv M_LOCKF 230Byte-range locking structures. 231.It Dv M_PROC 232Proc structures. 233.It Dv M_SUBPROC 234Proc sub-structures. 235.It Dv M_SEGMENT 236Segment for LFS. 237.It Dv M_LFSNODE 238LFS vnode private part. 239.It Dv M_FFSNODE 240FFS vnode private part. 241.It Dv M_MFSNODE 242MFS vnode private part. 243.It Dv M_NQLEASE 244Nqnfs lease. 245.It Dv M_NQMHOST 246Nqnfs host address table. 247.It Dv M_NETADDR 248Export host address structure. 249.It Dv M_NFSSVC 250Nfs server structure. 251.It Dv M_NFSUID 252Nfs uid mapping structure. 253.It Dv M_NFSD 254Nfs server daemon structure. 255.It Dv M_IPMOPTS 256Internet multicast options. 257.It Dv M_IPMADDR 258Internet multicast address. 259.It Dv M_IFMADDR 260Link-level multicast address. 261.It Dv M_MRTABLE 262Multicast routing tables. 263.It Dv M_ISOFSMNT 264ISOFS mount structure. 265.It Dv M_ISOFSNODE 266ISOFS vnode private part. 267.It Dv M_MSDOSFSMNT 268MSDOS FS mount structure. 269.It Dv M_MSDOSFSFAT 270MSDOS FS fat table. 271.It Dv M_MSDOSFSNODE 272MSDOS FS vnode private part. 273.It Dv M_TTYS 274Allocated tty structures. 275.It Dv M_EXEC 276Argument lists \*[Am] other mem used by exec. 277.It Dv M_MISCFSMNT 278Miscfs mount structures. 279.It Dv M_MISCFSNODE 280Miscfs vnode private part. 281.It Dv M_ADOSFSMNT 282Adosfs mount structures. 283.It Dv M_ADOSFSNODE 284Adosfs vnode private part. 285.It Dv M_ANODE 286Adosfs anode structures and tables. 287.It Dv M_IPQ 288IP packet queue entry. 289.It Dv M_AFS 290Andrew File System. 291.It Dv M_ADOSFSBITMAP 292Adosfs bitmap. 293.It Dv M_NFSSRVDESC 294NFS server descriptor. 295.It Dv M_NFSDIROFF 296NFS directory cookies. 297.It Dv M_NFSBIGFH 298NFS big filehandle. 299.It Dv M_EXT2FSNODE 300EXT2FS vnode private part. 301.It Dv M_VMSWAP 302VM swap structures. 303.It Dv M_VMPAGE 304VM page structures. 305.It Dv M_VMPBUCKET 306VM page buckets. 307.It Dv M_UVMAMAP 308UVM amap and related structs. 309.It Dv M_UVMAOBJ 310UVM aobj and related structs. 311.It Dv M_TEMP 312Misc temporary data buffers. 313.It Dv M_DMAMAP 314.Xr bus_dma 9 315structures. 316.It Dv M_IPFLOW 317IP flow entries. 318.It Dv M_USB 319USB general. 320.It Dv M_USBDEV 321USB permanent. 322.It Dv M_POOL 323Memory 324.Xr pool 9 325structures. 326.It Dv M_CODA 327Coda file system structures and tables. 328.It Dv M_FILECOREMNT 329Filecore FS mount structures. 330.It Dv M_FILECORENODE 331Filecore FS vnode private part. 332.It Dv M_RAIDFRAME 333RAIDframe structures and IO buffers. 334.It Dv M_USBHC 335USB host controller. 336.It Dv M_SECA 337security associations, key management. 338.It Dv M_IP6OPT 339IPv6 options. 340.It Dv M_IP6NDP 341IPv6 Neighbour Discovery. 342.It Dv M_NTFS 343Windows NT file system structures. 344.It Dv M_PAGEDEP 345File page dependencies. 346.It Dv M_INODEDEP 347Inode dependencies. 348.It Dv M_NEWBLK 349New block allocation. 350.It Dv M_BMSAFEMAP 351Block or frag allocated from cyl group map. 352.It Dv M_ALLOCDIRECT 353Block or frag dependency for an inode. 354.It Dv M_INDIRDEP 355Indirect block dependencies. 356.It Dv M_ALLOCINDIR 357Block dependency for an indirect block. 358.It Dv M_FREEFRAG 359Previously used frag for an inode. 360.It Dv M_FREEBLKS 361Blocks freed from an inode. 362.It Dv M_FREEFILE 363Inode deallocated. 364.It Dv M_DIRADD 365New directory entry. 366.It Dv M_MKDIR 367New directory. 368.It Dv M_DIRREM 369Directory entry deleted. 370.It Dv M_IP6RR 371IPv6 Router Renumbering Prefix. 372.It Dv M_RR_ADDR 373IPv6 Router Renumbering Ifid. 374.It Dv M_SOFTINTR 375Softinterrupt structures. 376.It Dv M_EMULDATA 377Per-process emulation data. 378.It Dv M_1394CTL 379IEEE 1394 control structures. 380.It Dv M_1394DATA 381IEEE 1394 data buffers. 382.It Dv M_PIPE 383Pipe structures. 384.It Dv M_AGP 385AGP memory. 386.It Dv M_PROP 387Kernel properties structures. 388.It Dv M_NEWDIRBLK 389Unclaimed new directory block (softdeps). 390.It Dv M_SMBIOD 391SMB network id daemon. 392.It Dv M_SMBCONN 393SMB connection id. 394.It Dv M_SMBRQ 395SMB request. 396.It Dv M_SMBDATA 397Miscellaneous SMB data. 398.It Dv M_SMBSTR 399SMB string data. 400.It Dv M_SMBTEMP 401Temporary SMB data. 402.It Dv M_ICONV 403ICONV data. 404.It Dv M_SMBNODE 405SMBFS node. 406.It Dv M_SMBNODENAME 407SMBFS node name. 408.It Dv M_SMBFSDATA 409SMBFS data. 410.It Dv M_SMBFSHASH 411SMBFS hash table. 412.It Dv M_SA 413Scheduler activations data structures 414.El 415.Pp 416Statistics based on the 417.Fa type 418argument is maintained only if the kernel option 419.Dv KMEMSTATS 420is used when compiling the kernel 421.Po 422the default in current 423.Nx 424kernels 425.Pc 426and can be examined by using 427.Sq vmstat -m . 428.Sh RETURN VALUES 429.Fn malloc 430returns a kernel virtual address that is suitably aligned for storage of 431any type of object. 432.Sh DIAGNOSTICS 433A kernel compiled with the 434.Dv DIAGNOSTIC 435configuration option attempts to detect memory corruption caused by 436such things as writing outside the allocated area and imbalanced calls to the 437.Fn malloc 438and 439.Fn free 440functions. 441Failing consistency checks will cause a panic or a system console message: 442.Bl -bullet -offset indent -compact 443.Pp 444.It 445panic: 446.Dq malloc - bogus type 447.It 448panic: 449.Dq malloc: out of space in kmem_map 450.It 451panic: 452.Dq malloc: allocation too large 453.It 454panic: 455.Dq malloc: wrong bucket 456.It 457panic: 458.Dq malloc: lost data 459.It 460panic: 461.Dq free: unaligned addr 462.It 463panic: 464.Dq free: duplicated free 465.It 466panic: 467.Dq free: multiple frees 468.It 469panic: 470.Dq init: minbucket too small/struct freelist too big 471.It 472.Dq multiply freed item Aq addr 473.It 474.Dq Data modified on freelist: Aq data object description 475.El 476.Sh SEE ALSO 477.Xr vmstat 1 478