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