.\"	$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