mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-24 11:29:10 +00:00
88cf6634a5
Obtained from: NetBSD w/changes to reflect current FreeBSD headers and diagnostic messages.
263 lines
8.9 KiB
Groff
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
|