NetBSD/share/man/man9/malloc.9

.\"	$NetBSD: malloc.9,v 1.19 2001/12/04 20:39:02 jdolecek 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 FOUNDATION 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 December 4, 2001
.Dt MALLOC 9
.Os
.Sh NAME
.Nm malloc ,
.Nm free
.Nd kernel memory allocator
.Sh SYNOPSIS
.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
Unlike its standard C library counterpart
.Pq Xr malloc 3 ,
the kernel version takes two more arguments.
.Pp
The
.Fa flags
argument further qualifies
.Fn malloc
operational characteristics as follows:
.Bl -tag -offset indent -width M_CANFAIL
.It Dv M_NOWAIT
Causes
.Fn malloc
to return
.Dv NULL
if the request cannot be immediately fulfilled due to resource shortage.
If this flag is not set
(see
.Dv M_WAITOK ) ,
.Fn malloc
will never return
.Dv NULL .
.It Dv M_WAITOK
By default,
.Fn malloc
may call
.Xr sleep 9
to wait for resources to be released by other processes, and this
flag represents this behaviour.
Note that
.Dv M_WAITOK
is conveniently defined to be 0, and hence may be or'ed into the
.Fa flags
argument to indicate that it's Ok to wait for resources.
.It Dv M_ZERO
Causes the allocated memory to be set to all zeros.
.It Dv M_CANFAIL
Changes behaviour for
.Dv M_WAITOK
case - if the requested memory size is bigger than
.Fn malloc
can ever allocate, return failure, rather than calling
.Xr panic 9 . This is different to M_NOWAIT, since
the call can still wait for resources.
.Pp
Rather than depending on
.Dv M_CANFAIL ,
kernel code should do proper bound checking itself. This
flag should only be used in cases where this is not feasible.
Since it can hide real kernel bugs, it's usage is
.Em strongly discouraged .
.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.
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_SONAME
Socket name.
.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_MAPMEM
Mapped memory descriptors.
.It Dv M_CRED
Credentials.
.It Dv M_PGRP
Process group header.
.It Dv M_SESSION
Session header.
.It Dv M_IOV
Large iov's.
.It Dv M_MOUNT
Vfs mount struct.
.It Dv M_FHANDLE
Network file handle.
.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_MISCFSNODE
Miscfs vnode private part.
.It Dv M_ADOSFSMNT
Adosfs mount structures.
.It Dv M_ADOSFSNODE
Adosfs vnode private part.
.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_NFSSRVDESC
NFS server descriptor.
.It Dv M_NFSDIROFF
NFS directory cookies.
.It Dv M_NFSBIGFH
NFS big filehandle.
.It Dv M_EXT2FSNODE
EXT2FS vnode private part.
.It Dv M_VMSWAP
VM swap structures.
.It Dv M_VMPAGE
VM page structures.
.It Dv M_VMPBUCKET
VM page buckets.
.It Dv M_UVMAMAP
UVM amap and related structs.
.It Dv M_UVMAOBJ
UVM aobj and related structs.
.It Dv M_TEMP
Misc temporary data buffers.
.It Dv M_DMAMAP
.Xr bus_dma 9
structures.
.It Dv M_IPFLOW
IP flow entries.
.It Dv M_USB
USB general.
.It Dv M_USBDEV
USB permanent.
.It Dv M_POOL
Memory
.Xr pool 9
structures.
.It Dv M_CODA
Coda file system structures and tables.
.It Dv M_FILECOREMNT
Filecore FS mount structures.
.It Dv M_FILECORENODE
Filecore FS vnode private part.
.It Dv M_RAIDFRAME
RAIDframe structures and IO buffers.
.It Dv M_USBHC
USB host controller.
.It Dv M_SECA
security associations, key management.
.It Dv M_IP6OPT
IPv6 options.
.It Dv M_IP6NDP
IPv6 Neighbour Discovery.
.It Dv M_NTFS
Windows NT file system structures.
.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_IP6RR
IPv6 Router Renumbering Prefix.
.It Dv M_RR_ADDR
IPv6 Router Renumbering Ifid.
.It Dv M_SOFTINTR
Softinterrupt structures.
.It Dv M_EMULDATA
Per-process emulation data.
.It Dv M_1394CTL
IEEE 1394 control structures.
.It Dv M_1394DATA
IEEE 1394 data buffers.
.It Dv M_PIPE
Pipe structures.
.It Dv M_AGP
AGP memory.
.It Dv M_PROP
Kernel properties structures.
.El
.Pp
Statistics based on the
.Fa type
argument is maintained only if the kernel option
.Dv KMEMSTATS
is used when compiling the kernel
.Po
the default in current
.Nx
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 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 imbalanced 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 init: 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 SEE ALSO
.Xr vmstat 1