1.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ 2.\" 3.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 29.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd June 16, 1996 38.Dt MALLOC 9 39.Os FreeBSD 40.Sh NAME 41.Nm malloc , 42.Nm MALLOC , 43.Nm free , 44.Nm FREE 45.Nd kernel memory management routines 46.Sh SYNOPSIS 47.Ft void * 48.Fn malloc "unsigned long size" "int type" "int flags" 49.Fn MALLOC "space" "cast" "unsigned long size" "int type" "int flags" 50.Ft void 51.Fn free "void *addr" "int type" 52.Fn FREE "void *addr" "int type" 53.Sh DESCRIPTION 54The 55.Fn malloc 56function allocates uninitialized memory in kernel address space for an 57object whose size is specified by 58.Fa size . 59.Fn free 60releases memory at address 61.Fa addr 62that was previously allocated by 63.Fn malloc 64for re-use. 65The 66.Fn MALLOC 67macro variant is functionally equivalent to 68.Bd -literal -offset indent 69(space) = (cast)malloc((u_long)(size), type, flags) 70.Ed 71.Pp 72and the 73.Fn FREE 74macro variant is equivalent to 75.Bd -literal -offset indent 76free((addr), type) 77.Ed 78.Pp 79Unlike its standard C library counterpart 80.Pq Xr malloc 3 , 81the kernel version takes two more arguments. The 82.Fa flags 83argument further qualifies 84.Fn malloc No Ns 's 85operational characteristics as follows: 86.Bl -tag -offset indent 87.It Dv M_NOWAIT 88Causes 89.Fn malloc 90to return 91.Dv NULL 92if the request cannot be immediately fulfilled due to resource shortage. 93Otherwise, 94.Fn malloc 95may call sleep to wait for resources to be released by other processes. 96If this flag is not set, 97.Fn malloc 98will never return 99.Dv NULL . 100Note that 101.Dv M_WAITOK 102is conveniently defined to be 0, and hence maybe or'ed into the 103.Fa flags 104argument to indicate that it's Ok to wait for resources. 105.El 106.Pp 107Currently, only one flag is defined. 108.Pp 109The 110.Fa type 111argument broadly identifies the kernel subsystem for which the allocated 112memory was needed, and is commonly used to maintain statistics about 113kernel memory usage. The following types are currently defined in 114the header file 115.Aq Pa sys/malloc.h : 116.Pp 117.Bd -literal 118#define M_FREE 0 /* should be on free list */ 119#define M_MBUF 1 /* mbuf */ 120#define M_DEVBUF 2 /* device driver memory */ 121#define M_SOCKET 3 /* socket structure */ 122#define M_PCB 4 /* protocol control block */ 123#define M_RTABLE 5 /* routing tables */ 124#define M_HTABLE 6 /* IMP host tables */ 125#define M_FTABLE 7 /* fragment reassembly header */ 126#define M_ZOMBIE 8 /* zombie proc status */ 127#define M_IFADDR 9 /* interface address */ 128#define M_SOOPTS 10 /* socket options */ 129#define M_SONAME 11 /* socket name */ 130#define M_NAMEI 12 /* namei path name buffer */ 131#define M_GPROF 13 /* kernel profiling buffer */ 132#define M_IOCTLOPS 14 /* ioctl data buffer */ 133#define M_MAPMEM 15 /* mapped memory descriptors */ 134#define M_CRED 16 /* credentials */ 135#define M_PGRP 17 /* process group header */ 136#define M_SESSION 18 /* session header */ 137#define M_IOV 19 /* large iov's */ 138#define M_MOUNT 20 /* vfs mount struct */ 139#define M_FHANDLE 21 /* network file handle */ 140#define M_NFSREQ 22 /* NFS request header */ 141#define M_NFSMNT 23 /* NFS mount structure */ 142#define M_NFSNODE 24 /* NFS vnode private part */ 143#define M_VNODE 25 /* Dynamically allocated vnodes */ 144#define M_CACHE 26 /* Dynamically allocated cache entries */ 145#define M_DQUOT 27 /* UFS quota entries */ 146#define M_UFSMNT 28 /* UFS mount structure */ 147#define M_SHM 29 /* SVID compatible shared memory segments */ 148#define M_VMMAP 30 /* VM map structures */ 149#define M_VMMAPENT 31 /* VM map entry structures */ 150#define M_VMOBJ 32 /* VM object structure */ 151#define M_VMOBJHASH 33 /* VM object hash structure */ 152#define M_VMPMAP 34 /* VM pmap */ 153#define M_VMPVENT 35 /* VM phys-virt mapping entry */ 154#define M_VMPAGER 36 /* XXX: VM pager struct */ 155#define M_VMPGDATA 37 /* XXX: VM pager private data */ 156#define M_FILE 38 /* Open file structure */ 157#define M_FILEDESC 39 /* Open file descriptor table */ 158#define M_LOCKF 40 /* Byte-range locking structures */ 159#define M_PROC 41 /* Proc structures */ 160#define M_SUBPROC 42 /* Proc sub-structures */ 161#define M_SEGMENT 43 /* Segment for LFS */ 162#define M_LFSNODE 44 /* LFS vnode private part */ 163#define M_FFSNODE 45 /* FFS vnode private part */ 164#define M_MFSNODE 46 /* MFS vnode private part */ 165#define M_NQLEASE 47 /* Nqnfs lease */ 166#define M_NQMHOST 48 /* Nqnfs host address table */ 167#define M_NETADDR 49 /* Export host address structure */ 168#define M_NFSSVC 50 /* Nfs server structure */ 169#define M_NFSUID 51 /* Nfs uid mapping structure */ 170#define M_NFSD 52 /* Nfs server daemon structure */ 171#define M_IPMOPTS 53 /* internet multicast options */ 172#define M_IPMADDR 54 /* internet multicast address */ 173#define M_IFMADDR 55 /* link-level multicast address */ 174#define M_MRTABLE 56 /* multicast routing tables */ 175#define M_ISOFSMNT 57 /* ISOFS mount structure */ 176#define M_ISOFSNODE 58 /* ISOFS vnode private part */ 177#define M_NFSRVDESC 59 /* NFS server socket descriptor */ 178#define M_NFSDIROFF 60 /* NFS directory offset data */ 179#define M_NFSBIGFH 61 /* NFS version 3 file handle */ 180#define M_MSDOSFSMNT 67 /* MSDOSFS mount structure */ 181#define M_MSDOSFSNODE 68 /* MSDOSFS vnode private part */ 182#define M_MSDOSFSFAT 69 /* MSDOSFS file allocation table */ 183#define M_DEVFSMNT 70 /* DEVFS mount structure */ 184#define M_DEVFSBACK 71 /* DEVFS Back node */ 185#define M_DEVFSFRONT 72 /* DEVFS Front node */ 186#define M_DEVFSNODE 73 /* DEVFS node */ 187#define M_TEMP 74 /* misc temporary data buffers */ 188#define M_TTYS 75 /* tty data structures */ 189#define M_GZIP 76 /* Gzip trees */ 190#define M_IPFW 77 /* IpFw/IpAcct chain's */ 191#define M_DEVL 78 /* isa_device lists in userconfig() */ 192#define M_PKTCLASS 79 /* structures used in packet classifier */ 193#define M_SYSCTL 80 /* sysctl internal magic */ 194#define M_SECA 81 /* security associations, key management */ 195#define M_BIOBUF 82 /* BIO buffer */ 196#define M_KTRACE 83 /* KTRACE */ 197#define M_SELECT 84 /* select() buffer */ 198#define M_GEOM_DEV 85 /* geometry device */ 199#define M_GEOM_MOD 86 /* geometry module */ 200#define M_GEOM_REQ 87 /* geometry request */ 201#define M_GEOM_MISC 88 /* geometry misc */ 202#define M_VFSCONF 89 /* vfsconf structure */ 203.Ed 204.Pp 205Statistics based on the 206.Fa type 207argument are maintained only if the kernel option 208.Dv KMEMSTATS 209is used when compiling the kernel 210(the default in 211.Tn FreeBSD 212kernels) 213and can be examined by using 214.Sq vmstat -m . 215.Sh RETURN VALUES 216.Fn malloc 217returns a kernel virtual address that is suitably aligned for storage of 218any type of object. 219.Sh SEE ALSO 220.Xr vmstat 8 221.Sh DIAGNOSTICS 222A kernel compiled with the 223.Dv DIAGNOSTIC 224configuration option attempts to detect detect memory corruption caused by 225such things as writing outside the allocated area and imbalanced calls to the 226.Fn malloc 227and 228.Fn free 229functions. Failing consistency checks will cause a panic or a system console 230message: 231.Bl -bullet -offset indent -compact 232.Pp 233.It 234panic: 235.Dq malloc: bogus type 236.It 237panic: 238.Dq malloc: allocation too large 239.It 240panic: 241.Dq malloc: wrong bucket 242.It 243panic: 244.Dq malloc: lost data 245.It 246panic: 247.Dq free: address 0x%x out of range 248.It 249panic: 250.Dq free: type %d out of range 251.It 252panic: 253.Dq free: unaligned addr Aq description of object 254.It 255panic: 256.Dq free: item modified 257.It 258panic: 259.Dq free: multiple free[s] 260.It 261.Dq Data modified on freelist: Aq description of object 262.El 263