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: src/share/man/man9/malloc.9,v 1.13.2.6 2002/03/16 02:20:28 archie Exp $ 38.\" $DragonFly: src/share/man/man9/kmalloc.9,v 1.2 2003/06/17 04:37:01 dillon Exp $ 39.\" 40.Dd June 16, 1996 41.Dt MALLOC 9 42.Os 43.Sh NAME 44.Nm malloc , 45.Nm MALLOC , 46.Nm free , 47.Nm FREE 48.Nd kernel memory management routines 49.Sh SYNOPSIS 50.In sys/types.h 51.In sys/malloc.h 52.Ft void * 53.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" 54.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" "int flags" 55.Ft void 56.Fn free "void *addr" "struct malloc_type *type" 57.Fn FREE "void *addr" "struct malloc_type *type" 58.Ft void * 59.Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 60.Ft void * 61.Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 62.Sh DESCRIPTION 63The 64.Fn malloc 65function allocates uninitialized memory in kernel address space for an 66object whose size is specified by 67.Fa size . 68.Pp 69.Fn free 70releases memory at address 71.Fa addr 72that was previously allocated by 73.Fn malloc 74for re-use. 75The memory is not zeroed. 76If 77.Fa addr 78is 79.Dv NULL , 80then 81.Fn free 82does nothing. 83.Pp 84The 85.Fn realloc 86function changes the size of the previously allocated memory referenced by 87.Fa addr 88to 89.Fa size 90bytes. 91The contents of the memory are unchanged up to the lesser of the new and 92old sizes. 93Note that the returned value may differ from 94.Fa addr . 95If the requested memory cannot be allocated, 96.Dv NULL 97is returned and the memory referenced by 98.Fa addr 99is valid and unchanged. 100If 101.Fa addr 102is 103.Dv NULL , 104the 105.Fn realloc 106function behaves identically to 107.Fn malloc 108for the specified size. 109.Pp 110The 111.Fn reallocf 112function call is identical to the realloc function call, except that it 113will free the passed pointer when the requested memory cannot be allocated. 114.Pp 115The 116.Fn MALLOC 117macro variant is functionally equivalent to 118.Bd -literal -offset indent 119(space) = (cast)malloc((u_long)(size), type, flags) 120.Ed 121.Pp 122and the 123.Fn FREE 124macro variant is equivalent to 125.Bd -literal -offset indent 126free((addr), type) 127.Ed 128.Pp 129Unlike its standard C library counterpart 130.Pq Xr malloc 3 , 131the kernel version takes two more arguments. The 132.Fa flags 133argument further qualifies 134.Fn malloc Ns 's 135operational characteristics as follows: 136.Bl -tag -width indent 137.It Dv M_NOWAIT 138Causes 139.Fn malloc , 140.Fn realloc , 141or 142.Fn reallocf 143to return 144.Dv NULL 145if the request cannot be immediately fulfilled due to resource shortage. 146Otherwise, the current process may be put to sleep to wait for 147resources to be released by other processes. 148If this flag is set, 149.Fn malloc 150will return 151.Dv NULL 152rather then block. 153Note that 154.Dv M_WAITOK 155is defined to be 0, meaning that blocking operation is the default. 156Also note that 157.Dv M_NOWAIT 158is required when running in an interrupt context. 159.It Dv M_ASLEEP 160Causes 161.Fn malloc , 162.Fn realloc , 163or 164.Fn reallocf 165to call 166.Fn asleep 167if the request cannot be immediately fulfilled due to a resource shortage. 168M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow 169the function to call 170.Fn asleep 171and return 172.Dv NULL 173immediately. It is expected that the caller will at some point call 174.Fn await 175and then retry the allocation. Depending on the routine in question, the 176caller may decide to propagate the temporary failure up the call chain 177and actually have some other higher level routine block on the async wait 178that the function queued. 179.It Dv M_WAITOK 180Indicates that it is Ok to wait for resources. It is unconveniently 181defined as 0 so care should be taken never to compare against this value 182directly or try to AND it as a flag. The default operation is to block 183until the memory allocation succeeds. 184.Fn malloc , 185.Fn realloc , 186and 187.Fn reallocf 188can only return 189.Dv NULL 190if 191.Dv M_NOWAIT 192is specified. 193.It Dv M_USE_RESERVE 194Indicates that the system can dig into its reserve in order to obtain the 195requested memory. This option used to be called M_KERNEL but has been 196renamed to something more obvious. This option has been deprecated and is 197slowly being removed from the kernel, and so should not be used with any new 198programming. 199.El 200.Pp 201The 202.Fa type 203argument is used to perform statistics on memory usage, and for 204basic sanity checks. 205The statistics can be examined by 206.Sq vmstat -m . 207.Pp 208A 209.Fa type 210is defined using the 211.Va malloc_type_t 212typedef via the 213.Fn MALLOC_DECLARE 214and 215.Fn MALLOC_DEFINE 216macros. 217.Bd -literal -offset indent 218/* sys/something/foo_extern.h */ 219 220MALLOC_DECLARE(M_FOOBUF); 221 222/* sys/something/foo_main.c */ 223 224MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 225 226/* sys/something/foo_subr.c */ 227 228\&... 229MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT); 230 231.Ed 232.Sh RETURN VALUES 233.Fn malloc , 234.Fn realloc , 235and 236.Fn reallocf 237return a kernel virtual address that is suitably aligned for storage of 238any type of object, or 239.Dv NULL 240if the request could not be satisfied (implying that 241.Dv M_NOWAIT 242was set). 243If 244.Dv M_ASLEEP 245was set and the function returns 246.Dv NULL , 247it will call 248.Fn asleep 249as a side effect. 250.Sh IMPLEMENTATION NOTES 251The memory allocator allocates memory in chunks that have size a power 252of two for requests up to the size of a page of memory. 253For larger requests, one or more pages is allocated. 254While it should not be relied upon, this information may be useful for 255optimizing the efficiency of memory use. 256.Sh SEE ALSO 257.Xr vmstat 8 258.Sh DIAGNOSTICS 259A kernel compiled with the 260.Dv DIAGNOSTIC 261configuration option attempts to detect memory corruption caused by 262such things as writing outside the allocated area and imbalanced calls to the 263.Fn malloc 264and 265.Fn free 266functions. 267Failing consistency checks will cause a panic or a system console 268message: 269.Bl -bullet -offset indent -compact 270.Pp 271.It 272panic: 273.Dq malloc: bogus type 274.It 275panic: 276.Dq malloc: allocation too large 277.It 278panic: 279.Dq malloc: wrong bucket 280.It 281panic: 282.Dq malloc: lost data 283.It 284panic: 285.Dq free: address 0x%x out of range 286.It 287panic: 288.Dq free: type %d out of range 289.It 290panic: 291.Dq free: unaligned addr Aq description of object 292.It 293panic: 294.Dq free: item modified 295.It 296panic: 297.Dq free: multiple free[s] 298.It 299.Dq Data modified on freelist: Aq description of object 300.El 301