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 No Ns 's 89operational characteristics as follows: 90.Bl -tag -width indent 91.It Dv M_NOWAIT 92Causes 93.Fn malloc 94to return 95.Dv NULL 96if the request cannot be immediately fulfilled due to resource shortage. 97Otherwise, 98.Fn malloc 99may call sleep to wait for resources to be released by other processes. 100If this flag is set, 101.Fn malloc 102will return 103.Dv NULL 104rather then block. Note that 105.Dv M_WAITOK 106is defined to be 0, meaning that blocking operation is the default. 107.It Dv M_ASLEEP 108Causes 109.Fn malloc 110to call 111.Fn asleep 112if the request cannot be immediately fulfilled due to a resource shortage. 113M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow 114malloc to call 115.Fn asleep 116and return 117.Dv NULL 118immediately. It is expected that the caller will at some point call 119.Fn await 120and then retry the allocation. Depending on the routine in question, the 121caller may decide to propagate the temporary failure up the call chain 122and actually have some other higher level routine block on the async wait 123that 124.Fn malloc 125queued. 126.It Dv M_WAITOK 127Indicates that it is Ok to wait for resources. It is unconveniently 128defined as 0 so care should be taken never to compare against this value 129directly or try to AND it as a flag. The default operation is to block 130until the memory allocation succeeds. 131.Fn malloc 132can only return 133.Dv NULL 134if 135.Dv M_NOWAIT 136is specified. 137.It Dv M_USE_RESERVE 138Indicates that the system can dig into its reserve in order to obtain the 139requested memory. This option used to be called M_KERNEL but has been 140renamed to something more obvious. This option has been depreciated and is 141slowly being removed from the kernel, and so should not be used with any new 142programming. 143.El 144.Pp 145The 146.Fa type 147argument is used to perform statistics on memory usage, and for 148basic sanity checks. 149The statistics can be examined by 150.Sq vmstat -m . 151.Pp 152A 153.Fa type 154is defined using the 155.Va malloc_type_t 156typedef via the 157.Fn MALLOC_DECLARE 158and 159.Fn MALLOC_DEFINE 160macros. 161.Bd -literal -offset indent 162/* sys/something/foo_extern.h */ 163 164MALLOC_DECLARE(M_FOOBUF); 165 166/* sys/something/foo_main.c */ 167 168MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 169 170/* sys/something/foo_subr.c */ 171 172... 173MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT); 174 175.Ed 176.Sh RETURN VALUES 177.Fn malloc 178returns a kernel virtual address that is suitably aligned for storage of 179any type of object, or 180.Dv NULL 181if the request could not be satisfied and 182.Dv M_NOWAIT 183was set. If 184.Dv M_ASLEEP 185was set and 186.Fn malloc 187returns 188.Dv NULL , 189it will call 190.Fn asleep 191as a side effect. 192.Sh SEE ALSO 193.Xr vmstat 8 194.Sh DIAGNOSTICS 195A kernel compiled with the 196.Dv DIAGNOSTIC 197configuration option attempts to detect memory corruption caused by 198such things as writing outside the allocated area and imbalanced calls to the 199.Fn malloc 200and 201.Fn free 202functions. Failing consistency checks will cause a panic or a system console 203message: 204.Bl -bullet -offset indent -compact 205.Pp 206.It 207panic: 208.Dq malloc: bogus type 209.It 210panic: 211.Dq malloc: allocation too large 212.It 213panic: 214.Dq malloc: wrong bucket 215.It 216panic: 217.Dq malloc: lost data 218.It 219panic: 220.Dq free: address 0x%x out of range 221.It 222panic: 223.Dq free: type %d out of range 224.It 225panic: 226.Dq free: unaligned addr Aq description of object 227.It 228panic: 229.Dq free: item modified 230.It 231panic: 232.Dq free: multiple free[s] 233.It 234.Dq Data modified on freelist: Aq description of object 235.El 236