356 lines
8.4 KiB
Groff
356 lines
8.4 KiB
Groff
.\" $NetBSD: malloc.9,v 1.8 1998/07/29 22:07:14 pk 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 June 16, 1996
|
|
.Dt MALLOC 9
|
|
.Os NetBSD
|
|
.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. The
|
|
.Fa flags
|
|
argument further qualifies
|
|
.Fn malloc No Ns 's
|
|
operational charateristics as follows:
|
|
.Bl -tag -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_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_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_CFS
|
|
Coda file system structures and tables.
|
|
.It Dv M_TEMP
|
|
Misc temporary data buffers.
|
|
.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 SEE ALSO
|
|
.Xr vmstat 8
|
|
.Sh DIAGNOSTICS
|
|
A kernel compiled with the
|
|
.Dv DIAGNOSTIC
|
|
configuration option attempts to detect 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
|