From 88cf6634a5669d5b2e8bc9570fdf37f37dc3c090 Mon Sep 17 00:00:00 2001 From: Mike Pritchard Date: Sat, 22 Mar 1997 23:50:21 +0000 Subject: [PATCH] Add malloc(9) to document the kernel malloc() and free() routines. Obtained from: NetBSD w/changes to reflect current FreeBSD headers and diagnostic messages. --- share/man/man9/Makefile | 7 +- share/man/man9/malloc.9 | 262 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 266 insertions(+), 3 deletions(-) create mode 100644 share/man/man9/malloc.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 9ce078ba9c93..25c757da6b7b 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 000000000000..a3c677c9c62b --- /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