1.\" $OpenBSD: malloc.9,v 1.26 2003/06/06 20:56:32 jmc Exp $ 2.\" $NetBSD: malloc.9,v 1.2 1996/10/30 05:29:54 lukem Exp $ 3.\" 4.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 5.\" All rights reserved. 6.\" 7.\" This code is derived from software contributed to The NetBSD Foundation 8.\" by Paul Kranenburg. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 30.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd June 16, 1996 39.Dt MALLOC 9 40.Os 41.Sh NAME 42.Nm malloc 43.Nd kernel memory allocator 44.Sh SYNOPSIS 45.Fd #include <sys/types.h> 46.Fd #include <sys/malloc.h> 47.Ft void * 48.Fn malloc "unsigned long size" "int type" "int flags" 49.Fn MALLOC "space" "cast" "unsigned long size" "int type" "int flags" 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 free 60releases memory at address 61.Fa addr 62that was previously allocated by 63.Fn malloc 64for re-use. 65The 66.Fn MALLOC 67macro variant is functionally equivalent to 68.Bd -literal -offset indent 69(space) = (cast)malloc((u_long)(size), type, flags) 70.Ed 71.Pp 72and the 73.Fn FREE 74macro variant is equivalent to 75.Bd -literal -offset indent 76free((caddr_t)(addr), type) 77.Ed 78.Pp 79These macros should only be used when the 80.Fa size 81argument is a constant. 82.Pp 83Unlike its standard C library counterpart 84.Pq Xr malloc 3 , 85the kernel version takes two more arguments. 86The 87.Fa flags 88argument further qualifies 89.Fn malloc No Ns 's 90operational characteristics as follows: 91.Bl -tag -width xxx -offset indent 92.It Dv M_NOWAIT 93Causes 94.Fn malloc 95to return 96.Dv NULL 97if the request cannot be immediately fulfilled due to resource shortage. 98Otherwise, 99.Fn malloc 100may call sleep to wait for resources to be released by other processes. 101If this flag is not set, 102.Fn malloc 103will never return 104.Dv NULL . 105Note that 106.Dv M_WAITOK 107is conveniently defined to be 0, and hence maybe or'ed into the 108.Fa flags 109argument to indicate that it's OK to wait for resources. 110.El 111.Pp 112Currently, only one flag is defined. 113.Pp 114The 115.Fa type 116argument broadly identifies the kernel subsystem for which the allocated 117memory was needed, and is commonly used to maintain statistics about 118kernel memory usage. 119The following types are currently defined: 120.Pp 121.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 122.It Dv M_FREE 123Should be on free list. 124.It Dv M_MBUF 125Mbuf memory. 126.It Dv M_DEVBUF 127Device driver memory. 128.It Dv M_DEBUG 129.Nm malloc 130debug structures. 131.It Dv M_PCB 132Protocol control block. 133.It Dv M_RTABLE 134Routing tables. 135.It Dv M_FTABLE 136Fragment reassembly header. 137.It Dv M_IFADDR 138Interface address. 139.It Dv M_SOOPTS 140Socket options. 141.It Dv M_SYSCTL 142Sysctl persistent buffers. 143.It Dv M_NAMEI 144Namei path name buffer. 145.It Dv M_IOCTLOPS 146Ioctl data buffer. 147.It Dv M_IOV 148Large IOVs. 149.It Dv M_MOUNT 150Vfs mount struct. 151.It Dv M_NFSREQ 152NFS request header. 153.It Dv M_NFSMNT 154NFS mount structure. 155.It Dv M_NFSNODE 156NFS vnode private part. 157.It Dv M_VNODE 158Dynamically allocated vnodes. 159.It Dv M_CACHE 160Dynamically allocated cache entries. 161.It Dv M_DQUOT 162UFS quota entries. 163.It Dv M_UFSMNT 164UFS mount structure. 165.It Dv M_SHM 166SVID compatible shared memory segments. 167.It Dv M_VMMAP 168VM map structures. 169.It Dv M_VMPMAP 170VM pmap data. 171.It Dv M_FILE 172Open file structure. 173.It Dv M_FILEDESC 174Open file descriptor table. 175.It Dv M_LOCKF 176Byte-range locking structures. 177.It Dv M_PROC 178Proc structures. 179.It Dv M_SUBPROC 180Proc sub-structures. 181.It Dv M_VCLUSTER 182Cluster for VFS. 183.It Dv M_MFSNODE 184MFS vnode private part. 185.It Dv M_NETADDR 186Export host address structure. 187.It Dv M_NFSSVC 188NFS server structure. 189.It Dv M_NFSUID 190NFS uid mapping structure. 191.It Dv M_NFSD 192NFS server daemon structure. 193.It Dv M_IPMOPTS 194Internet multicast options. 195.It Dv M_IPMADDR 196Internet multicast address. 197.It Dv M_IFMADDR 198Link-level multicast address. 199.It Dv M_MRTABLE 200Multicast routing tables. 201.It Dv M_ISOFSMNT 202ISOFS mount structure. 203.It Dv M_ISOFSNODE 204ISOFS vnode private part. 205.It Dv M_MSDOSFSMNT 206MSDOS FS mount structure. 207.It Dv M_MSDOSFSFAT 208MSDOS FS fat table. 209.It Dv M_MSDOSFSNODE 210MSDOS FS vnode private part. 211.It Dv M_TTYS 212Allocated tty structures. 213.It Dv M_EXEC 214Argument lists & other mem used by exec. 215.It Dv M_MISCFSMNT 216Miscfs mount structures. 217.It Dv M_ADOSFSMNT 218Adosfs mount structures. 219.It Dv M_ANODE 220Adosfs anode structures and tables. 221.It Dv M_ADOSFSBITMAP 222Adosfs bitmap. 223.It Dv M_EXT2FSNODE 224EXT2FS vnode private part. 225.It Dv M_PFKEY 226Pfkey data. 227.It Dv M_TDB 228Transforms database. 229.It Dv M_XDATA 230IPsec data. 231.It Dv M_VFS 232VFS file systems. 233.It Dv M_PAGEDEP 234File page dependencies. 235.It Dv M_INODEDEP 236Inode dependencies. 237.It Dv M_NEWBLK 238New block allocation. 239.It Dv M_VMSWAP 240VM swap structures. 241.It Dv M_RAIDFRAME 242RAIDframe data. 243.It Dv M_UVMAMAP 244UVM amap and related. 245.It Dv M_UVMAOBJ 246UVM aobj and related. 247.It Dv M_USB 248USB general. 249.It Dv M_USBDEV 250USB device driver. 251.It Dv M_USBHC 252USB host controller. 253.It Dv M_MEMDESC 254Memory range. 255.It Dv M_UFS_EXTATTR 256UFS Extended Attributes. 257.It Dv M_CREDENTIALS 258.Xr ipsec 4 259related credentials. 260.It Dv M_PACKET_TAGS 261Packet-attached information tags. 262.It Dv M1394CTL 263IEEE 1394 control structures. 264.It Dv M1394DATA 265IEEE 1394 data buffers. 266.It Dv M_IP6OPT 267IPv6 options. 268.It Dv M_IP6NDP 269IPv6 neighbour discovery structures. 270.It Dv M_IP6RR 271IPv6 router renumbering prefix. 272.It Dv M_RR_ADDR 273IPv6 router renumbering interface identifiers. 274.It Dv M_TEMP 275Miscellaneous temporary data buffers. 276.El 277.Pp 278Statistics based on the 279.Fa type 280argument are maintained only if the kernel option 281.Dv KMEMSTATS 282is used when compiling the kernel 283.Po the default in current\ \& 284.Ox 285kernels 286.Pc 287and can be examined by using 288.Sq vmstat -m . 289.Sh RETURN VALUES 290.Fn malloc 291returns a kernel virtual address that is suitably aligned for storage of 292any type of object. 293.Sh DIAGNOSTICS 294A kernel compiled with the 295.Dv DIAGNOSTIC 296configuration option attempts to detect memory corruption caused by 297such things as writing outside the allocated area and unbalanced calls to the 298.Fn malloc 299and 300.Fn free 301functions. 302Failing consistency checks will cause a panic or a system console message: 303.Bl -bullet -offset indent -compact 304.Pp 305.It 306panic: 307.Dq malloc - bogus type 308.It 309panic: 310.Dq malloc: out of space in kmem_map 311.It 312panic: 313.Dq malloc: allocation too large 314.It 315panic: 316.Dq malloc: wrong bucket 317.It 318panic: 319.Dq malloc: lost data 320.It 321panic: 322.Dq free: unaligned addr 323.It 324panic: 325.Dq free: duplicated free 326.It 327panic: 328.Dq free: multiple frees 329.It 330panic: 331.Dq kmeminit: minbucket too small/struct freelist too big 332.It 333.Dq multiply freed item Aq addr 334.It 335.Dq Data modified on freelist: Aq data object description 336.El 337.Sh DEBUGGING 338A kernel compiled with the 339.Cm MALLOC_DEBUG 340option allows for more extensive debugging of memory allocations. 341The 342.Va debug_malloc_type , 343.Va debug_malloc_size , 344.Va debug_malloc_size_lo 345and 346.Va debug_malloc_size_hi 347variables choose which allocation to debug. 348.Va debug_malloc_type 349should be set to the memory type and 350.Va debug_malloc_size 351should be set to the memory size to debug. 3520 can be used as a wildcard. 353.Va debug_malloc_size_lo 354and 355.Va debug_malloc_size_hi 356can be used to specify a range of sizes if the exact size to debug is not 357known. 358When those are used, 359.Va debug_malloc_size 360needs to be set to the wildcard. 361.Dv M_DEBUG 362can also be specified as an allocation type to force allocation with 363debugging. 364.Pp 365Every call to 366.Fn malloc 367with a memory type and size that matches the debugged type and size will 368allocate two virtual pages. 369The pointer returned will be aligned so that 370the requested area will end at the page boundary and the second virtual page 371will be left unmapped. 372This way we can catch reads and writes outside the allocated area. 373.Pp 374Every call to 375.Fn free 376with memory that was returned by the debugging malloc will cause the memory 377area to become unmapped so that we can catch dangling reads and writes to 378freed memory. 379.Pp 380There are no special diagnostics if any errors are caught by the debugging 381malloc. 382The errors will look like normal access to unmapped memory. 383On a memory access error, the 384.Ic show malloc 385command in 386.Xr ddb 4 387can be invoked to see what memory areas are allocated and freed. 388If the faulting address is within two pages from an address on the allocated 389list, there was an access outside the allocated area. 390If the faulting address is within two pages from an address on the free list, 391there was an access to freed memory. 392.Pp 393Care needs to be taken when using the 394.Cm MALLOC_DEBUG 395option: the memory consumption can run away pretty quickly and there is 396a severe performance degradation when allocating and freeing debugged memory 397types. 398.Sh SEE ALSO 399.Xr vmstat 8 400