.\"	$OpenBSD: malloc.9,v 1.47 2012/04/06 15:42:56 jsing 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.
.\"
.\" 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 $Mdocdate: April 6 2012 $
.Dt MALLOC 9
.Os
.Sh NAME
.Nm malloc ,
.Nm free
.Nd kernel memory allocator
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/malloc.h>
.Ft void *
.Fn malloc "unsigned long size" "int type" "int flags"
.Ft void
.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.
.Pp
The
.Fa flags
argument further qualifies malloc's
operational characteristics as follows:
.Bl -tag -width xxx -offset indent
.It Dv M_WAITOK
The same as having no other
.Fa flags
specified.
If memory is currently unavailable,
.Fn malloc
may call sleep to wait for resources to be released by other processes.
.It Dv M_NOWAIT
Causes
.Fn malloc
to return
.Dv NULL
if the request cannot be immediately fulfilled due to resource shortage.
One of
.Dv M_NOWAIT
or
.Dv M_WAITOK
must be specified.
.It Dv M_CANFAIL
In the
.Dv M_WAITOK
case, if not enough memory is available, return
.Dv NULL
instead of calling
.Xr panic 9 .
.Dv M_CANFAIL
has no effect if
.Dv M_NOWAIT
is specified.
.It Dv M_ZERO
Causes
.Fn malloc
to return zeroed memory.
.El
.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.
These statistics can be examined using
.Xr vmstat 8
or
.Xr systat 1
if either of the kernel
.Xr options 4
.Cm KMEMSTATS
or
.Cm DEBUG
are enabled.
.Pp
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_DEVBUF
Device driver memory.
.It Dv M_DEBUG
.Nm malloc
debug structures.
.It Dv M_PCB
Protocol control blocks.
.It Dv M_RTABLE
Routing tables.
.It Dv M_FTABLE
Fragment reassembly headers.
.It Dv M_IFADDR
Interface addresses.
.It Dv M_SOOPTS
Socket options.
.It Dv M_SYSCTL
Sysctl persistent buffers.
.It Dv M_IOCTLOPS
Ioctl data buffers.
.It Dv M_IOV
Large IOVs.
.It Dv M_MOUNT
VFS mount structs.
.It Dv M_NFSREQ
NFS request headers.
.It Dv M_NFSMNT
NFS mount structures.
.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 structures.
.It Dv M_SHM
SVID compatible shared memory segments.
.It Dv M_VMMAP
VM map structures.
.It Dv M_SEM
SVID compatible semaphores.
.It Dv M_DIRHASH
UFS directory hash structures.
.It Dv M_ACPI
ACPI structures.
.It Dv M_VMPMAP
VM pmap data.
.It Dv M_FILE
Open file structures.
.It Dv M_FILEDESC
Open file descriptor tables.
.It Dv M_PROC
Proc structures.
.It Dv M_SUBPROC
Proc sub-structures.
.It Dv M_VCLUSTER
Cluster for VFS.
.It Dv M_MFSNODE
MFS vnode private part.
.It Dv M_NETADDR
Export host address structures.
.It Dv M_NFSSVC
NFS server structures.
.It Dv M_NFSD
NFS server daemon structures.
.It Dv M_IPMOPTS
Internet multicast options.
.It Dv M_IPMADDR
Internet multicast addresses.
.It Dv M_IFMADDR
Link-level multicast addresses.
.It Dv M_MRTABLE
Multicast routing tables.
.It Dv M_ISOFSMNT
ISOFS mount structures.
.It Dv M_ISOFSNODE
ISOFS vnode private part.
.It Dv M_MSDOSFSMNT
MSDOS FS mount structures.
.It Dv M_MSDOSFSFAT
MSDOS FS FAT tables.
.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
Miscellaneous FS mount structures.
.It Dv M_PFKEY
Pfkey data.
.It Dv M_TDB
Transforms database.
.It Dv M_XDATA
IPsec data.
.It Dv M_PAGEDEP
File page dependencies.
.It Dv M_INODEDEP
Inode dependencies.
.It Dv M_NEWBLK
New block allocation.
.It Dv M_UVMAMAP
UVM amap and related.
.It Dv M_UVMAOBJ
UVM aobj and related.
.It Dv M_USB
USB general.
.It Dv M_USBDEV
USB device driver.
.It Dv M_USBHC
USB host controller.
.It Dv M_MEMDESC
Memory range.
.It Dv M_CRYPTO_DATA
.Xr crypto 4
data buffers.
.It Dv M_CREDENTIALS
.Xr ipsec 4
related credentials.
.It Dv M_PACKET_TAGS
Packet-attached information tags.
.It Dv M_EMULDATA
Per process emulation data.
.It Dv M_IP6OPT
IPv6 options.
.It Dv M_IP6NDP
IPv6 neighbour discovery structures.
.It Dv M_TEMP
Miscellaneous temporary data buffers.
.It Dv M_NTFSMNT
NTFS mount structures.
.It Dv M_NTFSNTNODE
NTFS ntnode information.
.It Dv M_NTFSNODE
NTFS fnode information.
.It Dv M_NTFSDIR
NTFS directory buffers.
.It Dv M_NTFSHASH
NTFS ntnode hash tables.
.It Dv M_NTFSVATTR
NTFS file attribute information.
.It Dv M_NTFSRDATA
NTFS resident data.
.It Dv M_NTFSDECOMP
NTFS decompression temporary storage.
.It Dv M_NTFSRUN
NTFS vrun storage.
.It Dv M_KEVENT
.Xr kqueue 2
data structures.
.It Dv M_BLUETOOTH
Bluetooth data structures.
.It Dv M_BWMETER
Multicast upcall bandwidth meters.
.It Dv M_UDFMOUNT
UDF mount structures.
.It Dv M_UDFFENTRY
UDF file entries.
.It Dv M_UDFFID
UDF file ID.
.It Dv M_BTHIDEV
Bluetooth HID.
.It Dv M_AGP
AGP memory.
.It Dv M_DRM
Direct Rendering Manager.
.El
.Sh RETURN VALUES
.Fn malloc
returns a kernel virtual address that is suitably aligned for storage of
any type of object.
.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:
.Pp
.Bl -bullet -offset indent -compact
.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.
The
.Va debug_malloc_type ,
.Va debug_malloc_size ,
.Va debug_malloc_size_lo
and
.Va debug_malloc_size_hi
variables choose which allocation to debug.
.Va debug_malloc_type
should be set to the memory type and
.Va debug_malloc_size
should be set to the memory size 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,
.Va debug_malloc_size
needs to be set to the wildcard.
.Dv M_DEBUG
can also be specified as an allocation type to force allocation with
debugging.
.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.
On a memory access error, the
.Ic show malloc
command in
.Xr ddb 4
can be invoked to see what memory areas are allocated and freed.
If the faulting address is within two pages from an address on the allocated
list, there was an access outside the allocated area.
If the faulting address is within two pages from an address on the free list,
there was an access to freed memory.
.Pp
Care needs to be taken 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.
.Sh SEE ALSO
.Xr systat 1 ,
.Xr vmstat 8