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.42 2005/02/22 17:20:20 brueffer Exp $ 38.\" $DragonFly: src/share/man/man9/kmalloc.9,v 1.8 2008/01/19 08:23:17 swildner Exp $ 39.\" 40.Dd January 15, 2010 41.Dt KMALLOC 9 42.Os 43.Sh NAME 44.Nm kmalloc , 45.Nm MALLOC , 46.Nm kfree , 47.Nm FREE , 48.Nm krealloc , 49.Nm MALLOC_DEFINE , 50.Nm MALLOC_DECLARE 51.Nd kernel memory management routines 52.Sh SYNOPSIS 53.In sys/types.h 54.In sys/malloc.h 55.Ft void * 56.Fn kmalloc "unsigned long size" "struct malloc_type *type" "int flags" 57.Fn MALLOC space cast "unsigned long size" "struct malloc_type *type" "int flags" 58.Ft void 59.Fn kfree "void *addr" "struct malloc_type *type" 60.Fn FREE "void *addr" "struct malloc_type *type" 61.Ft void * 62.Fn krealloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 63.Fn MALLOC_DECLARE type 64.In sys/param.h 65.In sys/malloc.h 66.In sys/kernel.h 67.Fn MALLOC_DEFINE type shortdesc longdesc 68.Sh DESCRIPTION 69The 70.Fn kmalloc 71function allocates uninitialized memory in kernel address space for an 72object whose size is specified by 73.Fa size . 74.Pp 75The 76.Fn kfree 77function releases memory at address 78.Fa addr 79that was previously allocated by 80.Fn kmalloc 81for re-use. 82The memory is not zeroed. 83The kernel implementation of 84.Fn kfree 85does not allow 86.Fa addr 87to be 88.Dv NULL . 89.Pp 90The 91.Fn krealloc 92function changes the size of the previously allocated memory referenced by 93.Fa addr 94to 95.Fa size 96bytes. 97The contents of the memory are unchanged up to the lesser of the new and 98old sizes. 99Note that the returned value may differ from 100.Fa addr . 101If the requested memory cannot be allocated, 102.Dv NULL 103is returned and the memory referenced by 104.Fa addr 105is valid and unchanged. 106If 107.Fa addr 108is 109.Dv NULL , 110the 111.Fn krealloc 112function behaves identically to 113.Fn kmalloc 114for the specified size. 115.Pp 116The 117.Fn MALLOC 118macro variant is functionally equivalent to 119.Bd -literal -offset indent 120(space) = (cast)kmalloc((u_long)(size), type, flags) 121.Ed 122.Pp 123and the 124.Fn FREE 125macro variant is equivalent to 126.Bd -literal -offset indent 127kfree((addr), type) 128.Ed 129.Pp 130Unlike its standard C library counterpart 131.Pq Xr malloc 3 , 132the kernel version takes two more arguments. 133The 134.Fa flags 135argument further qualifies 136.Fn kmalloc Ns 's 137operational characteristics as follows: 138.Bl -tag -width indent 139.It Dv M_ZERO 140Causes the allocated memory to be set to all zeros. 141.It Dv M_NOWAIT 142Causes 143.Fn kmalloc 144and 145.Fn krealloc , 146to return 147.Dv NULL 148if the request cannot be immediately fulfilled due to resource shortage. 149Note that 150.Dv M_NOWAIT 151is required when running in an interrupt context. 152.It Dv M_WAITOK 153Indicates that it is OK to wait for resources. 154If the request cannot be immediately fulfilled, the current process is put 155to sleep to wait for resources to be released by other processes. 156The 157.Fn kmalloc 158and 159.Fn krealloc , 160functions cannot return 161.Dv NULL 162if 163.Dv M_WAITOK 164is specified. 165.It Dv M_INTWAIT 166Indicates 167.Fn kmalloc 168to dig into the system's reserved free pages looking for enough room to 169perform the allocation. 170This is typically used in interrupts where you cannot afford 171.Fn kmalloc 172to fail. 173.It Dv M_USE_RESERVE 174Indicates that the system can dig into its reserve in order to obtain the 175requested memory. 176This option used to be called 177.Dv M_KERNEL 178but has been renamed to something more obvious. 179This option has been deprecated and is slowly being removed from the kernel, 180and so should not be used with any new code. 181.El 182.Pp 183Exactly one of either 184.Dv M_WAITOK 185or 186.Dv M_NOWAIT 187must be specified. 188.Pp 189The 190.Fa type 191argument is used to perform statistics on memory usage, and for 192basic sanity checks. 193It can be used to identify multiple allocations. 194The statistics can be examined by 195.Sq vmstat -m . 196.Pp 197A 198.Fa type 199is defined using the 200.Va malloc_type_t 201typedef via the 202.Fn MALLOC_DECLARE 203and 204.Fn MALLOC_DEFINE 205macros. 206.Bd -literal -offset indent 207/* sys/something/foo_extern.h */ 208 209MALLOC_DECLARE(M_FOOBUF); 210 211/* sys/something/foo_main.c */ 212 213MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 214 215/* sys/something/foo_subr.c */ 216 217\&... 218MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT); 219 220.Ed 221.Sh IMPLEMENTATION NOTES 222The memory allocator allocates memory in chunks that have size a power 223of two for requests up to the size of a page of memory. 224For larger requests, one or more pages is allocated. 225While it should not be relied upon, this information may be useful for 226optimizing the efficiency of memory use. 227.Sh RETURN VALUES 228The 229.Fn kmalloc 230and 231.Fn krealloc , 232functions return a kernel virtual address that is suitably aligned for 233storage of any type of object, or 234.Dv NULL 235if the request could not be satisfied (implying that 236.Dv M_NOWAIT 237was set). 238.Sh DIAGNOSTICS 239A kernel compiled with the 240.Dv INVARIANTS 241configuration option attempts to detect memory corruption caused by 242such things as writing outside the allocated area and imbalanced calls to the 243.Fn kmalloc 244and 245.Fn kfree 246functions. 247Failing consistency checks will cause a panic or a system console 248message. 249.Sh SEE ALSO 250.Xr vmstat 8 , 251.Xr contigmalloc 9 , 252.Xr memory 9 , 253.Xr vnode 9 254