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 November 15, 2012 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_NODUMP 127For allocations greater than page size, causes the allocated 128memory to be excluded from kernel core dumps. 129.It Dv M_NOWAIT 130Causes 131.Fn malloc , 132.Fn realloc , 133and 134.Fn reallocf 135to return 136.Dv NULL 137if the request cannot be immediately fulfilled due to resource shortage. 138Note that 139.Dv M_NOWAIT 140is required when running in an interrupt context. 141.It Dv M_WAITOK 142Indicates that it is OK to wait for resources. 143If the request cannot be immediately fulfilled, the current process is put 144to sleep to wait for resources to be released by other processes. 145The 146.Fn malloc , 147.Fn realloc , 148and 149.Fn reallocf 150functions cannot return 151.Dv NULL 152if 153.Dv M_WAITOK 154is specified. 155.It Dv M_USE_RESERVE 156Indicates that the system can use its reserve of memory to satisfy the 157request. 158This option should only be used in combination with 159.Dv M_NOWAIT 160when an allocation failure cannot be tolerated by the caller without 161catastrophic effects on the system. 162.El 163.Pp 164Exactly one of either 165.Dv M_WAITOK 166or 167.Dv M_NOWAIT 168must be specified. 169.Pp 170The 171.Fa type 172argument is used to perform statistics on memory usage, and for 173basic sanity checks. 174It can be used to identify multiple allocations. 175The statistics can be examined by 176.Sq vmstat -m . 177.Pp 178A 179.Fa type 180is defined using 181.Vt "struct malloc_type" 182via the 183.Fn MALLOC_DECLARE 184and 185.Fn MALLOC_DEFINE 186macros. 187.Bd -literal -offset indent 188/* sys/something/foo_extern.h */ 189 190MALLOC_DECLARE(M_FOOBUF); 191 192/* sys/something/foo_main.c */ 193 194MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 195 196/* sys/something/foo_subr.c */ 197 198\&... 199buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT); 200 201.Ed 202.Pp 203In order to use 204.Fn MALLOC_DEFINE , 205one must include 206.In sys/param.h 207(instead of 208.In sys/types.h ) 209and 210.In sys/kernel.h . 211.Sh IMPLEMENTATION NOTES 212The memory allocator allocates memory in chunks that have size a power 213of two for requests up to the size of a page of memory. 214For larger requests, one or more pages is allocated. 215While it should not be relied upon, this information may be useful for 216optimizing the efficiency of memory use. 217.Pp 218Programmers should be careful not to confuse the malloc flags 219.Dv M_NOWAIT 220and 221.Dv M_WAITOK 222with the 223.Xr mbuf 9 224flags 225.Dv M_DONTWAIT 226and 227.Dv M_WAIT . 228.Sh CONTEXT 229.Fn malloc , 230.Fn realloc 231and 232.Fn reallocf 233may not be called from fast interrupts handlers. 234When called from threaded interrupts, 235.Fa flags 236must contain 237.Dv M_NOWAIT . 238.Pp 239.Fn malloc , 240.Fn realloc 241and 242.Fn reallocf 243may sleep when called with 244.Dv M_WAITOK . 245.Fn free 246never sleeps. 247.Pp 248Any calls to 249.Fn malloc 250(even with 251.Dv M_NOWAIT ) 252or 253.Fn free 254when holding a 255.Xr vnode 9 256interlock, will cause a LOR (Lock Order Reversal) due to the 257intertwining of VM Objects and Vnodes. 258.Sh RETURN VALUES 259The 260.Fn malloc , 261.Fn realloc , 262and 263.Fn reallocf 264functions return a kernel virtual address that is suitably aligned for 265storage of any type of object, or 266.Dv NULL 267if the request could not be satisfied (implying that 268.Dv M_NOWAIT 269was set). 270.Sh DIAGNOSTICS 271A kernel compiled with the 272.Dv INVARIANTS 273configuration option attempts to detect memory corruption caused by 274such things as writing outside the allocated area and imbalanced calls to the 275.Fn malloc 276and 277.Fn free 278functions. 279Failing consistency checks will cause a panic or a system console 280message. 281.Sh SEE ALSO 282.Xr vmstat 8 , 283.Xr contigmalloc 9 , 284.Xr memguard 9 , 285.Xr vnode 9 286