.\" $OpenBSD: malloc.9,v 1.19 2002/07/17 11:49:36 art Exp $ .\" $NetBSD: malloc.9,v 1.2 1996/10/30 05:29:54 lukem Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the NetBSD .\" Foundation, Inc. and its contributors. .\" 4. Neither the name of The NetBSD Foundation nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd June 16, 1996 .Dt MALLOC 9 .Os .Sh NAME .Nm malloc .Nd kernel memory allocator .Sh SYNOPSIS .Fd #include .Fd #include .Ft void * .Fn malloc "unsigned long size" "int type" "int flags" .Fn MALLOC "space" "cast" "unsigned long size" "int type" "int flags" .Ft void .Fn free "void *addr" "int type" .Fn FREE "void *addr" "int type" .Sh DESCRIPTION The .Fn malloc function allocates uninitialized memory in kernel address space for an object whose size is specified by .Fa size . .Fn free releases memory at address .Fa addr that was previously allocated by .Fn malloc for re-use. The .Fn MALLOC macro variant is functionally equivalent to .Bd -literal -offset indent (space) = (cast)malloc((u_long)(size), type, flags) .Ed .Pp and the .Fn FREE macro variant is equivalent to .Bd -literal -offset indent free((caddr_t)(addr), type) .Ed .Pp These macros should only be used when the .Fa size argument is a constant. .Pp Unlike its standard C library counterpart .Pq Xr malloc 3 , the kernel version takes two more arguments. The .Fa flags argument further qualifies .Fn malloc No Ns 's operational characteristics as follows: .Bl -tag -width xxx -offset indent .It Dv M_NOWAIT Causes .Fn malloc to return .Dv NULL if the request cannot be immediately fulfilled due to resource shortage. Otherwise, .Fn malloc may call sleep to wait for resources to be released by other processes. If this flag is not set, .Fn malloc will never return .Dv NULL . Note that .Dv M_WAITOK is conveniently defined to be 0, and hence maybe or'ed into the .Fa flags argument to indicate that it's Ok to wait for resources. .El .Pp Currently, only one flag is defined. .Pp The .Fa type argument broadly identifies the kernel subsystem for which the allocated memory was needed, and is commonly used to maintain statistics about kernel memory usage. The following types are currently defined: .Pp .Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact .It Dv M_FREE Should be on free list. .It Dv M_MBUF Mbuf memory. .It Dv M_DEVBUF Device driver memory. .It Dv M_SOCKET Socket structure. .It Dv M_PCB Protocol control block. .It Dv M_RTABLE Routing tables. .It Dv M_HTABLE IMP host tables. .It Dv M_FTABLE Fragment reassembly header. .It Dv M_ZOMBIE Zombie proc status .It Dv M_IFADDR Interface address. .It Dv M_SOOPTS Socket options. .It Dv M_SYSCTL Sysctl persistent buffers. .It Dv M_NAMEI Namei path name buffer. .It Dv M_GPROF Kernel profiling buffer. .It Dv M_IOCTLOPS Ioctl data buffer. .It Dv M_CRED Credentials. .It Dv M_PGRP Process group header. .It Dv M_SESSION Session header. .It Dv M_IOV Large IOVs. .It Dv M_MOUNT Vfs mount struct. .It Dv M_NFSREQ NFS request header. .It Dv M_NFSMNT NFS mount structure. .It Dv M_NFSNODE NFS vnode private part. .It Dv M_VNODE Dynamically allocated vnodes. .It Dv M_CACHE Dynamically allocated cache entries. .It Dv M_DQUOT UFS quota entries. .It Dv M_UFSMNT UFS mount structure. .It Dv M_SHM SVID compatible shared memory segments. .It Dv M_VMMAP VM map structures. .It Dv M_VMMAPENT VM map entry structures. .It Dv M_VMOBJ VM object structure. .It Dv M_VMOBJHASH VM object hash structure. .It Dv M_VMPMAP VM pmap. .It Dv M_VMPVENT VM phys-virt mapping entry. .It Dv M_VMPAGER XXX: VM pager struct. .It Dv M_VMPGDATA XXX: VM pager private data. .It Dv M_FILE Open file structure. .It Dv M_FILEDESC Open file descriptor table. .It Dv M_LOCKF Byte-range locking structures. .It Dv M_PROC Proc structures. .It Dv M_SUBPROC Proc sub-structures. .It Dv M_SEGMENT Segment for LFS. .It Dv M_LFSNODE LFS vnode private part. .It Dv M_FFSNODE FFS vnode private part. .It Dv M_MFSNODE MFS vnode private part. .It Dv M_NQLEASE Nqnfs lease. .It Dv M_NQMHOST Nqnfs host address table. .It Dv M_NETADDR Export host address structure. .It Dv M_NFSSVC Nfs server structure. .It Dv M_NFSUID Nfs uid mapping structure. .It Dv M_NFSD Nfs server daemon structure. .It Dv M_IPMOPTS Internet multicast options. .It Dv M_IPMADDR Internet multicast address. .It Dv M_IFMADDR Link-level multicast address. .It Dv M_MRTABLE Multicast routing tables. .It Dv M_ISOFSMNT ISOFS mount structure. .It Dv M_ISOFSNODE ISOFS vnode private part. .It Dv M_MSDOSFSMNT MSDOS FS mount structure. .It Dv M_MSDOSFSFAT MSDOS FS fat table. .It Dv M_MSDOSFSNODE MSDOS FS vnode private part. .It Dv M_TTYS Allocated tty structures. .It Dv M_EXEC Argument lists & other mem used by exec. .It Dv M_MISCFSMNT Miscfs mount structures. .It Dv M_ADOSFSMNT Adosfs mount structures. .It Dv M_ANODE Adosfs anode structures and tables. .It Dv M_IPQ IP packet queue entry. .It Dv M_AFS Andrew File System. .It Dv M_ADOSFSBITMAP Adosfs bitmap. .It Dv M_EXT2FSNODE EXT2FS vnode private part. .It Dv M_PFIL Packer filter. .It Dv M_PFKEY Pfkey data. .It Dv M_TDB Transforms database. .It Dv M_XDATA IPsec data. .It Dv M_VFS VFS file systems. .It Dv M_PAGEDEP File page dependencies. .It Dv M_INODEDEP Inode dependencies. .It Dv M_NEWBLK New block allocation. .It Dv M_BMSAFEMAP Block or frag allocated from cyl group map. .It Dv M_ALLOCDIRECT Block or frag dependency for an inode. .It Dv M_INDIRDEP Indirect block dependencies. .It Dv M_ALLOCINDIR Block dependency for an indirect block. .It Dv M_FREEFRAG Previously used frag for an inode. .It Dv M_FREEBLKS Blocks freed from an inode. .It Dv M_FREEFILE Inode deallocated. .It Dv M_DIRADD New directory entry. .It Dv M_MKDIR New directory. .It Dv M_DIRREM Directory entry deleted. .It Dv M_VMPBUCKET VM page buckets. .It Dv M_VMSWAP VM swap structures. .It Dv M_RAIDFRAME Raidframe data. .It Dv M_UVMAMAP UVM amap and realted. .It Dv M_UVMAOBJ UVM aobj and realted. .It Dv M_POOL Pool memory. .It Dv M_USB USB general. .It Dv M_USBDEV USB device driver. .It Dv M_USBHC USB host controller. .It Dv M_PIPE Pipe structures. .It Dv M_MEMDESC Memory range. .It Dv M_DEBUG .Xr malloc 9 debug structures. .It Dv M_KNOTE Kernel event queue. .It Dv M_CRYPTO_DATA Cryptographic framework data buffers. .It Dv M_IPSEC_POLICY .Xr ipsec 4 SPD structures. .It Dv M_CREDENTIALS .Xr ipsec 4 related credentials. .It Dv M_PACKET_TAGS Packet-attached information tags. .It Dv M_CRYPTO_OPS Cryptographic framework operation request structures. .It Dv M_IP6OPT IPv6 options. .It Dv M_IP6NDP IPv6 neighbour discovery structures. .It Dv M_IP6RR IPv6 router renumbering prefix. .It Dv M_RR_ADDR IPv6 router renumbering interface identifiers. .It Dv M_TEMP Miscellaneous temporary data buffers. .El .Pp Statistics based on the .Fa type argument are maintained only if the kernel option .Dv KMEMSTATS is used when compiling the kernel .Po the default in current\ \& .Ox kernels .Pc and can be examined by using .Sq vmstat -m . .Sh RETURN VALUES .Fn malloc returns a kernel virtual address that is suitably aligned for storage of any type of object. .Sh SEE ALSO .Xr vmstat 8 .Sh DIAGNOSTICS A kernel compiled with the .Dv DIAGNOSTIC configuration option attempts to detect memory corruption caused by such things as writing outside the allocated area and unbalanced calls to the .Fn malloc and .Fn free functions. Failing consistency checks will cause a panic or a system console message: .Bl -bullet -offset indent -compact .Pp .It panic: .Dq malloc - bogus type .It panic: .Dq malloc: out of space in kmem_map .It panic: .Dq malloc: allocation too large .It panic: .Dq malloc: wrong bucket .It panic: .Dq malloc: lost data .It panic: .Dq free: unaligned addr .It panic: .Dq free: duplicated free .It panic: .Dq free: multiple frees .It panic: .Dq kmeminit: minbucket too small/struct freelist too big .It .Dq multiply freed item Aq addr .It .Dq Data modified on freelist: Aq data object description .El .Sh DEBUGGING A kernel compiled with the .Cm MALLOC_DEBUG option allows for more extensive debugging of memory allocations. You can choose which allocation to debug with the .Va debug_malloc_type , .Va debug_malloc_size , .Va debug_malloc_size_lo and .Va debug_malloc_size_hi variables. .Va debug_malloc_type should be set to the memory type and .Va debug_malloc_size should be set to the memory size you want to debug. 0 can be used as a wildcard. .Va debug_malloc_size_lo and .Va debug_malloc_size_hi Can be used to specify a range of sizes if the exact size to debug is not known. When those are used, you need to set .Va debug_malloc_size to the wildcard. .Pp Every call to .Fn malloc with a memory type and size that matches the debugged type and size will allocate two virtual pages. The pointer returned will be aligned so that the requested area will end at the page boundary and the second virtual page will be left unmapped. This way we can catch reads and writes outside the allocated area. .Pp Every call to .Fn free with memory that was returned by the debugging malloc will cause the memory area to become unmapped so that we can catch dangling reads and writes to freed memory. .Pp There are no special diagnostics if any errors are caught by the debugging malloc. The errors will look like normal access to unmapped memory. When you get a memory access error, you can invoke the .Ic show malloc command in .Xr ddb 4 to see what memory areas are allocated and freed. If the faulting address is within two pages from an address on the allocated list, you have gotten an access outside the allocated area. If the faulting address is within two pages from an address on the free list, you have gotten an access to freed memory. .Pp You have to be very careful when using the .Cm MALLOC_DEBUG option: the memory consumption can run away pretty quickly and there is a severe performance degradation when allocating and freeing debugged memory types.