freebsd-dev/share/man/man9/malloc.9
Mike Pritchard 88cf6634a5 Add malloc(9) to document the kernel malloc() and free() routines.
Obtained from: NetBSD w/changes to reflect current FreeBSD headers
and diagnostic messages.
1997-03-22 23:50:21 +00:00

263 lines
8.9 KiB
Groff

.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 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 FreeBSD
.Sh NAME
.Nm malloc ,
.Nm MALLOC ,
.Nm free ,
.Nm FREE
.Nd kernel memory management routines
.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((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 characteristics 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 in
the header file
.Aq Pa sys/malloc.h :
.Pp
.Bd -literal
#define M_FREE 0 /* should be on free list */
#define M_MBUF 1 /* mbuf */
#define M_DEVBUF 2 /* device driver memory */
#define M_SOCKET 3 /* socket structure */
#define M_PCB 4 /* protocol control block */
#define M_RTABLE 5 /* routing tables */
#define M_HTABLE 6 /* IMP host tables */
#define M_FTABLE 7 /* fragment reassembly header */
#define M_ZOMBIE 8 /* zombie proc status */
#define M_IFADDR 9 /* interface address */
#define M_SOOPTS 10 /* socket options */
#define M_SONAME 11 /* socket name */
#define M_NAMEI 12 /* namei path name buffer */
#define M_GPROF 13 /* kernel profiling buffer */
#define M_IOCTLOPS 14 /* ioctl data buffer */
#define M_MAPMEM 15 /* mapped memory descriptors */
#define M_CRED 16 /* credentials */
#define M_PGRP 17 /* process group header */
#define M_SESSION 18 /* session header */
#define M_IOV 19 /* large iov's */
#define M_MOUNT 20 /* vfs mount struct */
#define M_FHANDLE 21 /* network file handle */
#define M_NFSREQ 22 /* NFS request header */
#define M_NFSMNT 23 /* NFS mount structure */
#define M_NFSNODE 24 /* NFS vnode private part */
#define M_VNODE 25 /* Dynamically allocated vnodes */
#define M_CACHE 26 /* Dynamically allocated cache entries */
#define M_DQUOT 27 /* UFS quota entries */
#define M_UFSMNT 28 /* UFS mount structure */
#define M_SHM 29 /* SVID compatible shared memory segments */
#define M_VMMAP 30 /* VM map structures */
#define M_VMMAPENT 31 /* VM map entry structures */
#define M_VMOBJ 32 /* VM object structure */
#define M_VMOBJHASH 33 /* VM object hash structure */
#define M_VMPMAP 34 /* VM pmap */
#define M_VMPVENT 35 /* VM phys-virt mapping entry */
#define M_VMPAGER 36 /* XXX: VM pager struct */
#define M_VMPGDATA 37 /* XXX: VM pager private data */
#define M_FILE 38 /* Open file structure */
#define M_FILEDESC 39 /* Open file descriptor table */
#define M_LOCKF 40 /* Byte-range locking structures */
#define M_PROC 41 /* Proc structures */
#define M_SUBPROC 42 /* Proc sub-structures */
#define M_SEGMENT 43 /* Segment for LFS */
#define M_LFSNODE 44 /* LFS vnode private part */
#define M_FFSNODE 45 /* FFS vnode private part */
#define M_MFSNODE 46 /* MFS vnode private part */
#define M_NQLEASE 47 /* Nqnfs lease */
#define M_NQMHOST 48 /* Nqnfs host address table */
#define M_NETADDR 49 /* Export host address structure */
#define M_NFSSVC 50 /* Nfs server structure */
#define M_NFSUID 51 /* Nfs uid mapping structure */
#define M_NFSD 52 /* Nfs server daemon structure */
#define M_IPMOPTS 53 /* internet multicast options */
#define M_IPMADDR 54 /* internet multicast address */
#define M_IFMADDR 55 /* link-level multicast address */
#define M_MRTABLE 56 /* multicast routing tables */
#define M_ISOFSMNT 57 /* ISOFS mount structure */
#define M_ISOFSNODE 58 /* ISOFS vnode private part */
#define M_NFSRVDESC 59 /* NFS server socket descriptor */
#define M_NFSDIROFF 60 /* NFS directory offset data */
#define M_NFSBIGFH 61 /* NFS version 3 file handle */
#define M_MSDOSFSMNT 67 /* MSDOSFS mount structure */
#define M_MSDOSFSNODE 68 /* MSDOSFS vnode private part */
#define M_MSDOSFSFAT 69 /* MSDOSFS file allocation table */
#define M_DEVFSMNT 70 /* DEVFS mount structure */
#define M_DEVFSBACK 71 /* DEVFS Back node */
#define M_DEVFSFRONT 72 /* DEVFS Front node */
#define M_DEVFSNODE 73 /* DEVFS node */
#define M_TEMP 74 /* misc temporary data buffers */
#define M_TTYS 75 /* tty data structures */
#define M_GZIP 76 /* Gzip trees */
#define M_IPFW 77 /* IpFw/IpAcct chain's */
#define M_DEVL 78 /* isa_device lists in userconfig() */
#define M_PKTCLASS 79 /* structures used in packet classifier */
#define M_SYSCTL 80 /* sysctl internal magic */
#define M_SECA 81 /* security associations, key management */
#define M_BIOBUF 82 /* BIO buffer */
#define M_KTRACE 83 /* KTRACE */
#define M_SELECT 84 /* select() buffer */
#define M_GEOM_DEV 85 /* geometry device */
#define M_GEOM_MOD 86 /* geometry module */
#define M_GEOM_REQ 87 /* geometry request */
#define M_GEOM_MISC 88 /* geometry misc */
#define M_VFSCONF 89 /* vfsconf structure */
.Ed
.Pp
Statistics based on the
.Fa type
argument are maintained only if the kernel option
.Dv KMEMSTATS
is used when compiling the kernel
(the default in
.Tn FreeBSD
kernels)
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: allocation too large
.It
panic:
.Dq malloc: wrong bucket
.It
panic:
.Dq malloc: lost data
.It
panic:
.Dq free: address 0x%x out of range
.It
panic:
.Dq free: type %d out of range
.It
panic:
.Dq free: unaligned addr Aq description of object
.It
panic:
.Dq free: item modified
.It
panic:
.Dq free: multiple free[s]
.It
.Dq Data modified on freelist: Aq description of object
.El