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.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 21.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" POSSIBILITY OF SUCH DAMAGE. 28.\" 29.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ 30.\" $FreeBSD$ 31.\" 32.Dd October 23, 2008 33.Dt MALLOC 9 34.Os 35.Sh NAME 36.Nm malloc , 37.Nm free , 38.Nm realloc , 39.Nm reallocf , 40.Nm MALLOC_DEFINE , 41.Nm MALLOC_DECLARE 42.Nd kernel memory management routines 43.Sh SYNOPSIS 44.In sys/types.h 45.In sys/malloc.h 46.Ft void * 47.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" 48.Ft void 49.Fn free "void *addr" "struct malloc_type *type" 50.Ft void * 51.Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 52.Ft void * 53.Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 54.Fn MALLOC_DECLARE type 55.In sys/param.h 56.In sys/malloc.h 57.In sys/kernel.h 58.Fn MALLOC_DEFINE type shortdesc longdesc 59.Sh DESCRIPTION 60The 61.Fn malloc 62function allocates uninitialized memory in kernel address space for an 63object whose size is specified by 64.Fa size . 65.Pp 66The 67.Fn free 68function releases memory at address 69.Fa addr 70that was previously allocated by 71.Fn malloc 72for re-use. 73The memory is not zeroed. 74If 75.Fa addr 76is 77.Dv NULL , 78then 79.Fn free 80does nothing. 81.Pp 82The 83.Fn realloc 84function changes the size of the previously allocated memory referenced by 85.Fa addr 86to 87.Fa size 88bytes. 89The contents of the memory are unchanged up to the lesser of the new and 90old sizes. 91Note that the returned value may differ from 92.Fa addr . 93If the requested memory cannot be allocated, 94.Dv NULL 95is returned and the memory referenced by 96.Fa addr 97is valid and unchanged. 98If 99.Fa addr 100is 101.Dv NULL , 102the 103.Fn realloc 104function behaves identically to 105.Fn malloc 106for the specified size. 107.Pp 108The 109.Fn reallocf 110function is identical to 111.Fn realloc 112except that it 113will free the passed pointer when the requested memory cannot be allocated. 114.Pp 115Unlike its standard C library counterpart 116.Pq Xr malloc 3 , 117the kernel version takes two more arguments. 118The 119.Fa flags 120argument further qualifies 121.Fn malloc Ns 's 122operational characteristics as follows: 123.Bl -tag -width indent 124.It Dv M_ZERO 125Causes the allocated memory to be set to all zeros. 126.It Dv M_NOWAIT 127Causes 128.Fn malloc , 129.Fn realloc , 130and 131.Fn reallocf 132to return 133.Dv NULL 134if the request cannot be immediately fulfilled due to resource shortage. 135Note that 136.Dv M_NOWAIT 137is required when running in an interrupt context. 138.It Dv M_WAITOK 139Indicates that it is OK to wait for resources. 140If the request cannot be immediately fulfilled, the current process is put 141to sleep to wait for resources to be released by other processes. 142The 143.Fn malloc , 144.Fn realloc , 145and 146.Fn reallocf 147functions cannot return 148.Dv NULL 149if 150.Dv M_WAITOK 151is specified. 152.It Dv M_USE_RESERVE 153Indicates that the system can dig into its reserve in order to obtain the 154requested memory. 155This option used to be called 156.Dv M_KERNEL 157but has been renamed to something more obvious. 158This option has been deprecated and is slowly being removed from the kernel, 159and so should not be used with any new programming. 160.El 161.Pp 162Exactly one of either 163.Dv M_WAITOK 164or 165.Dv M_NOWAIT 166must be specified. 167.Pp 168The 169.Fa type 170argument is used to perform statistics on memory usage, and for 171basic sanity checks. 172It can be used to identify multiple allocations. 173The statistics can be examined by 174.Sq vmstat -m . 175.Pp 176A 177.Fa type 178is defined using 179.Vt "struct malloc_type" 180via the 181.Fn MALLOC_DECLARE 182and 183.Fn MALLOC_DEFINE 184macros. 185.Bd -literal -offset indent 186/* sys/something/foo_extern.h */ 187 188MALLOC_DECLARE(M_FOOBUF); 189 190/* sys/something/foo_main.c */ 191 192MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 193 194/* sys/something/foo_subr.c */ 195 196\&... 197buf = malloc(sizeof *buf, M_FOOBUF, M_NOWAIT); 198 199.Ed 200.Pp 201In order to use 202.Fn MALLOC_DEFINE , 203one must include 204.In sys/param.h 205(instead of 206.In sys/types.h ) 207and 208.In sys/kernel.h . 209.Sh IMPLEMENTATION NOTES 210The memory allocator allocates memory in chunks that have size a power 211of two for requests up to the size of a page of memory. 212For larger requests, one or more pages is allocated. 213While it should not be relied upon, this information may be useful for 214optimizing the efficiency of memory use. 215.Pp 216Programmers should be careful not to confuse the malloc flags 217.Dv M_NOWAIT 218and 219.Dv M_WAITOK 220with the 221.Xr mbuf 9 222flags 223.Dv M_DONTWAIT 224and 225.Dv M_WAIT . 226.Sh CONTEXT 227.Fn malloc , 228.Fn realloc 229and 230.Fn reallocf 231may not be called from fast interrupts handlers. 232When called from threaded interrupts, 233.Fa flags 234must contain 235.Dv M_NOWAIT . 236.Pp 237.Fn malloc , 238.Fn realloc 239and 240.Fn reallocf 241may sleep when called with 242.Dv M_WAITOK . 243.Fn free 244never sleeps. 245.Pp 246Any calls to 247.Fn malloc 248(even with 249.Dv M_NOWAIT ) 250or 251.Fn free 252when holding a 253.Xr vnode 9 254interlock, will cause a LOR (Lock Order Reversal) due to the 255intertwining of VM Objects and Vnodes. 256.Sh RETURN VALUES 257The 258.Fn malloc , 259.Fn realloc , 260and 261.Fn reallocf 262functions return a kernel virtual address that is suitably aligned for 263storage of any type of object, or 264.Dv NULL 265if the request could not be satisfied (implying that 266.Dv M_NOWAIT 267was set). 268.Sh DIAGNOSTICS 269A kernel compiled with the 270.Dv INVARIANTS 271configuration option attempts to detect memory corruption caused by 272such things as writing outside the allocated area and imbalanced calls to the 273.Fn malloc 274and 275.Fn free 276functions. 277Failing consistency checks will cause a panic or a system console 278message. 279.Sh SEE ALSO 280.Xr vmstat 8 , 281.Xr contigmalloc 9 , 282.Xr memguard 9 , 283.Xr vnode 9 284