man/man9/malloc.9

.\"	$OpenBSD: malloc.9,v 1.18 2001/07/17 15:52:56 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 <sys/types.h>
.Fd #include <sys/malloc.h>
.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 malloc_deb_type ,
.Va malloc_deb_size ,
.Va malloc_deb_size_lo
and
.Va malloc_deb_size_hi
variables.
.Va malloc_deb_type
should be set to the memory type and
.Va malloc_deb_size
should be set to the memory size you want to debug.
0 can be used as a wildcard.
.Va malloc_deb_size_lo
and
.Va malloc_deb_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 malloc_deb_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.