Add malloc(9) to document the kernel malloc() and free() routines.

Obtained from: NetBSD w/changes to reflect current FreeBSD headers
and diagnostic messages.

2 files changed, 266 insertions, 3 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 9ce078b..25c757d 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -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
diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9
new file mode 100644
index 0000000..a3c677c
--- /dev/null
+++ b/share/man/man9/malloc.9
@@ -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