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 January 28, 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 dig into its reserve in order to obtain the 157requested memory. 158This option used to be called 159.Dv M_KERNEL 160but has been renamed to something more obvious. 161This option has been deprecated and is slowly being removed from the kernel, 162and so should not be used with any new programming. 163.El 164.Pp 165Exactly one of either 166.Dv M_WAITOK 167or 168.Dv M_NOWAIT 169must be specified. 170.Pp 171The 172.Fa type 173argument is used to perform statistics on memory usage, and for 174basic sanity checks. 175It can be used to identify multiple allocations. 176The statistics can be examined by 177.Sq vmstat -m . 178.Pp 179A 180.Fa type 181is defined using 182.Vt "struct malloc_type" 183via the 184.Fn MALLOC_DECLARE 185and 186.Fn MALLOC_DEFINE 187macros. 188.Bd -literal -offset indent 189/* sys/something/foo_extern.h */ 190 191MALLOC_DECLARE(M_FOOBUF); 192 193/* sys/something/foo_main.c */ 194 195MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 196 197/* sys/something/foo_subr.c */ 198 199\&... 200buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT); 201 202.Ed 203.Pp 204In order to use 205.Fn MALLOC_DEFINE , 206one must include 207.In sys/param.h 208(instead of 209.In sys/types.h ) 210and 211.In sys/kernel.h . 212.Sh IMPLEMENTATION NOTES 213The memory allocator allocates memory in chunks that have size a power 214of two for requests up to the size of a page of memory. 215For larger requests, one or more pages is allocated. 216While it should not be relied upon, this information may be useful for 217optimizing the efficiency of memory use. 218.Pp 219Programmers should be careful not to confuse the malloc flags 220.Dv M_NOWAIT 221and 222.Dv M_WAITOK 223with the 224.Xr mbuf 9 225flags 226.Dv M_DONTWAIT 227and 228.Dv M_WAIT . 229.Sh CONTEXT 230.Fn malloc , 231.Fn realloc 232and 233.Fn reallocf 234may not be called from fast interrupts handlers. 235When called from threaded interrupts, 236.Fa flags 237must contain 238.Dv M_NOWAIT . 239.Pp 240.Fn malloc , 241.Fn realloc 242and 243.Fn reallocf 244may sleep when called with 245.Dv M_WAITOK . 246.Fn free 247never sleeps. 248.Pp 249Any calls to 250.Fn malloc 251(even with 252.Dv M_NOWAIT ) 253or 254.Fn free 255when holding a 256.Xr vnode 9 257interlock, will cause a LOR (Lock Order Reversal) due to the 258intertwining of VM Objects and Vnodes. 259.Sh RETURN VALUES 260The 261.Fn malloc , 262.Fn realloc , 263and 264.Fn reallocf 265functions return a kernel virtual address that is suitably aligned for 266storage of any type of object, or 267.Dv NULL 268if the request could not be satisfied (implying that 269.Dv M_NOWAIT 270was set). 271.Sh DIAGNOSTICS 272A kernel compiled with the 273.Dv INVARIANTS 274configuration option attempts to detect memory corruption caused by 275such things as writing outside the allocated area and imbalanced calls to the 276.Fn malloc 277and 278.Fn free 279functions. 280Failing consistency checks will cause a panic or a system console 281message. 282.Sh SEE ALSO 283.Xr vmstat 8 , 284.Xr contigmalloc 9 , 285.Xr memguard 9 , 286.Xr vnode 9 287