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