Add malloc(9) to document the kernel malloc() and free() routines.
Obtained from: NetBSD w/changes to reflect current FreeBSD headers and diagnostic messages.
This commit is contained in:
Mike Pritchard
parent
1c2eb98219
commit
88cf6634a5
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=24126
@ -1,9 +1,9 @@
|
||||
# $Id: Makefile,v 1.27 1997/03/22 22:06:05 mpp Exp $
|
||||
# $Id: Makefile,v 1.28 1997/03/22 22:21:36 mpp Exp $
|
||||
|
||||
MAN9= MD5.9 at_shutdown.9 at_fork.9 at_exit.9 boot.9 cd.9 copy.9 \
|
||||
devfs_add_devswf.9 \
|
||||
devfs_link.9 fetch.9 ifnet.9 intro.9 inittodr.9 kernacc.9 mi_switch.9 \
|
||||
panic.9 physio.9 psignal.9 \
|
||||
devfs_link.9 fetch.9 ifnet.9 intro.9 inittodr.9 kernacc.9 malloc.9 \
|
||||
mi_switch.9 panic.9 physio.9 psignal.9 \
|
||||
resettodr.9 rtalloc.9 rtentry.9 scsiconf.9 sd.9 sleep.9 spl.9 st.9 \
|
||||
store.9 style.9 time.9 timeout.9 uio.9 \
|
||||
vnode.9 vget.9 vput.9 vref.9 vrele.9 vslock.9 \
|
||||
@ -27,6 +27,7 @@ MLINKS+= at_exit.9 rm_at_exit.9
|
||||
MLINKS+= at_fork.9 rm_at_fork.9
|
||||
MLINKS+= ifnet.9 ifaddr.9 ifnet.9 ifqueue.9 ifnet.9 if_data.9
|
||||
MLINKS+= kernacc.9 useracc.9
|
||||
MLINKS+= malloc.9 free.9 malloc.9 MALLOC.9 malloc.9 FREE.9
|
||||
MLINKS+= mi_switch.9 cpu_switch.9
|
||||
MLINKS+= psignal.9 pgsignal.9 psignal.9 gsignal.9
|
||||
MLINKS+= rtalloc.9 rtalloc_ign.9 rtalloc.9 rtalloc1.9
|
||||
|
||||
262
share/man/man9/malloc.9
Normal file
262
share/man/man9/malloc.9
Normal file
@ -0,0 +1,262 @@
|
||||
.\" $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
|
||||
Loading…
Reference in New Issue
Block a user