441 lines
10 KiB
Groff
441 lines
10 KiB
Groff
.\" $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
|