1.\" 2.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 3.\" All rights reserved. 4.\" 5.\" This code is derived from software contributed to The NetBSD Foundation 6.\" by Paul Kranenburg. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the NetBSD 19.\" Foundation, Inc. and its contributors. 20.\" 4. Neither the name of The NetBSD Foundation nor the names of its 21.\" contributors may be used to endorse or promote products derived 22.\" from this software without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 25.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 26.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 27.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 28.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34.\" POSSIBILITY OF SUCH DAMAGE. 35.\" 36.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ 37.\" $FreeBSD$ 38.\" 39.Dd June 16, 1996 40.Dt MALLOC 9 41.Os FreeBSD 42.Sh NAME 43.Nm malloc , 44.Nm MALLOC , 45.Nm free , 46.Nm FREE 47.Nd kernel memory management routines 48.Sh SYNOPSIS 49.Fd #include <sys/types.h> 50.Fd #include <sys/malloc.h> 51.Ft void * 52.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" 53.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" "int flags" 54.Ft void 55.Fn free "void *addr" "struct malloc_type *type" 56.Fn FREE "void *addr" "struct malloc_type *type" 57.Sh DESCRIPTION 58The 59.Fn malloc 60function allocates uninitialized memory in kernel address space for an 61object whose size is specified by 62.Fa size . 63.Fn free 64releases memory at address 65.Fa addr 66that was previously allocated by 67.Fn malloc 68for re-use. The memory is not zeroed. 69The 70.Fn MALLOC 71macro variant is functionally equivalent to 72.Bd -literal -offset indent 73(space) = (cast)malloc((u_long)(size), type, flags) 74.Ed 75.Pp 76and the 77.Fn FREE 78macro variant is equivalent to 79.Bd -literal -offset indent 80free((addr), type) 81.Ed 82.Pp 83Unlike its standard C library counterpart 84.Pq Xr malloc 3 , 85the kernel version takes two more arguments. The 86.Fa flags 87argument further qualifies 88.Fn malloc Ns 's 89operational characteristics as follows: 90.Bl -tag -width indent 91.It Dv M_ZERO 92Causes the allocated memory to be set to all zeros. 93.It Dv M_NOWAIT 94Causes 95.Fn malloc 96to return 97.Dv NULL 98if the request cannot be immediately fulfilled due to resource shortage. 99Otherwise, 100.Fn malloc 101may call sleep to wait for resources to be released by other processes. 102If this flag is set, 103.Fn malloc 104will return 105.Dv NULL 106rather then block. Note that 107.Dv M_WAITOK 108is defined to be 0, meaning that blocking operation is the default. 109.It Dv M_ASLEEP 110Causes 111.Fn malloc 112to call 113.Fn asleep 114if the request cannot be immediately fulfilled due to a resource shortage. 115M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow 116malloc to call 117.Fn asleep 118and return 119.Dv NULL 120immediately. It is expected that the caller will at some point call 121.Fn await 122and then retry the allocation. Depending on the routine in question, the 123caller may decide to propagate the temporary failure up the call chain 124and actually have some other higher level routine block on the async wait 125that 126.Fn malloc 127queued. 128.It Dv M_WAITOK 129Indicates that it is Ok to wait for resources. It is unconveniently 130defined as 0 so care should be taken never to compare against this value 131directly or try to AND it as a flag. The default operation is to block 132until the memory allocation succeeds. 133.Fn malloc 134can only return 135.Dv NULL 136if 137.Dv M_NOWAIT 138is specified. 139.It Dv M_USE_RESERVE 140Indicates that the system can dig into its reserve in order to obtain the 141requested memory. This option used to be called M_KERNEL but has been 142renamed to something more obvious. This option has been depreciated and is 143slowly being removed from the kernel, and so should not be used with any new 144programming. 145.El 146.Pp 147The 148.Fa type 149argument is used to perform statistics on memory usage, and for 150basic sanity checks. 151The statistics can be examined by 152.Sq vmstat -m . 153.Pp 154A 155.Fa type 156is defined using the 157.Va malloc_type_t 158typedef via the 159.Fn MALLOC_DECLARE 160and 161.Fn MALLOC_DEFINE 162macros. 163.Bd -literal -offset indent 164/* sys/something/foo_extern.h */ 165 166MALLOC_DECLARE(M_FOOBUF); 167 168/* sys/something/foo_main.c */ 169 170MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 171 172/* sys/something/foo_subr.c */ 173 174\&... 175MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT); 176 177.Ed 178.Sh RETURN VALUES 179.Fn malloc 180returns a kernel virtual address that is suitably aligned for storage of 181any type of object, or 182.Dv NULL 183if the request could not be satisfied and 184.Dv M_NOWAIT 185was set. If 186.Dv M_ASLEEP 187was set and 188.Fn malloc 189returns 190.Dv NULL , 191it will call 192.Fn asleep 193as a side effect. 194.Sh SEE ALSO 195.Xr vmstat 8 196.Sh DIAGNOSTICS 197A kernel compiled with the 198.Dv DIAGNOSTIC 199configuration option attempts to detect memory corruption caused by 200such things as writing outside the allocated area and imbalanced calls to the 201.Fn malloc 202and 203.Fn free 204functions. 205Failing consistency checks will cause a panic or a system console 206message: 207.Bl -bullet -offset indent -compact 208.Pp 209.It 210panic: 211.Dq malloc: bogus type 212.It 213panic: 214.Dq malloc: allocation too large 215.It 216panic: 217.Dq malloc: wrong bucket 218.It 219panic: 220.Dq malloc: lost data 221.It 222panic: 223.Dq free: address 0x%x out of range 224.It 225panic: 226.Dq free: type %d out of range 227.It 228panic: 229.Dq free: unaligned addr Aq description of object 230.It 231panic: 232.Dq free: item modified 233.It 234panic: 235.Dq free: multiple free[s] 236.It 237.Dq Data modified on freelist: Aq description of object 238.El 239