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 June 13, 2018 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 "size_t size" "struct malloc_type *type" "int flags" 48.Ft void * 49.Fn malloc_domain "size_t size" "struct malloc_type *type" "int domain" "int flags" 50.Ft void * 51.Fn mallocarray "size_t nmemb" "size_t size" "struct malloc_type *type" "int flags" 52.Ft void 53.Fn free "void *addr" "struct malloc_type *type" 54.Ft void 55.Fn free_domain "void *addr" "struct malloc_type *type" 56.Ft void * 57.Fn realloc "void *addr" "size_t size" "struct malloc_type *type" "int flags" 58.Ft void * 59.Fn reallocf "void *addr" "size_t size" "struct malloc_type *type" "int flags" 60.Fn MALLOC_DECLARE type 61.In sys/param.h 62.In sys/malloc.h 63.In sys/kernel.h 64.Fn MALLOC_DEFINE type shortdesc longdesc 65.Sh DESCRIPTION 66The 67.Fn malloc 68function allocates uninitialized memory in kernel address space for an 69object whose size is specified by 70.Fa size . 71.Pp 72The 73.Fn malloc_domain 74variant allocates the object from the specified memory domain. Memory allocated 75with this function should be returned with 76.Fn free_domain . 77See 78.Xr numa 9 for more details. 79.Pp 80The 81.Fn mallocarray 82function allocates uninitialized memory in kernel address space for an 83array of 84.Fa nmemb 85entries whose size is specified by 86.Fa size . 87.Pp 88The 89.Fn free 90function releases memory at address 91.Fa addr 92that was previously allocated by 93.Fn malloc 94for re-use. 95The memory is not zeroed. 96If 97.Fa addr 98is 99.Dv NULL , 100then 101.Fn free 102does nothing. 103.Pp 104The 105.Fn realloc 106function changes the size of the previously allocated memory referenced by 107.Fa addr 108to 109.Fa size 110bytes. 111The contents of the memory are unchanged up to the lesser of the new and 112old sizes. 113Note that the returned value may differ from 114.Fa addr . 115If the requested memory cannot be allocated, 116.Dv NULL 117is returned and the memory referenced by 118.Fa addr 119is valid and unchanged. 120If 121.Fa addr 122is 123.Dv NULL , 124the 125.Fn realloc 126function behaves identically to 127.Fn malloc 128for the specified size. 129.Pp 130The 131.Fn reallocf 132function is identical to 133.Fn realloc 134except that it 135will free the passed pointer when the requested memory cannot be allocated. 136.Pp 137Unlike its standard C library counterpart 138.Pq Xr malloc 3 , 139the kernel version takes two more arguments. 140The 141.Fa flags 142argument further qualifies 143.Fn malloc Ns 's 144operational characteristics as follows: 145.Bl -tag -width indent 146.It Dv M_ZERO 147Causes the allocated memory to be set to all zeros. 148.It Dv M_NODUMP 149For allocations greater than page size, causes the allocated 150memory to be excluded from kernel core dumps. 151.It Dv M_NOWAIT 152Causes 153.Fn malloc , 154.Fn realloc , 155and 156.Fn reallocf 157to return 158.Dv NULL 159if the request cannot be immediately fulfilled due to resource shortage. 160Note that 161.Dv M_NOWAIT 162is required when running in an interrupt context. 163.It Dv M_WAITOK 164Indicates that it is OK to wait for resources. 165If the request cannot be immediately fulfilled, the current process is put 166to sleep to wait for resources to be released by other processes. 167The 168.Fn malloc , 169.Fn mallocarray , 170.Fn realloc , 171and 172.Fn reallocf 173functions cannot return 174.Dv NULL 175if 176.Dv M_WAITOK 177is specified. 178If the multiplication of 179.Fa nmemb 180and 181.Fa size 182would cause an integer overflow, the 183.Fn mallocarray 184function induces a panic. 185.It Dv M_USE_RESERVE 186Indicates that the system can use its reserve of memory to satisfy the 187request. 188This option should only be used in combination with 189.Dv M_NOWAIT 190when an allocation failure cannot be tolerated by the caller without 191catastrophic effects on the system. 192.It Dv M_EXEC 193Indicates that the system should allocate executable memory. 194If this flag is not set, the system will not allocate executable memory. 195Not all platforms enforce a distinction between executable and 196non-executable memory. 197.El 198.Pp 199Exactly one of either 200.Dv M_WAITOK 201or 202.Dv M_NOWAIT 203must be specified. 204.Pp 205The 206.Fa type 207argument is used to perform statistics on memory usage, and for 208basic sanity checks. 209It can be used to identify multiple allocations. 210The statistics can be examined by 211.Sq vmstat -m . 212.Pp 213A 214.Fa type 215is defined using 216.Vt "struct malloc_type" 217via the 218.Fn MALLOC_DECLARE 219and 220.Fn MALLOC_DEFINE 221macros. 222.Bd -literal -offset indent 223/* sys/something/foo_extern.h */ 224 225MALLOC_DECLARE(M_FOOBUF); 226 227/* sys/something/foo_main.c */ 228 229MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 230 231/* sys/something/foo_subr.c */ 232 233\&... 234buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT); 235 236.Ed 237.Pp 238In order to use 239.Fn MALLOC_DEFINE , 240one must include 241.In sys/param.h 242(instead of 243.In sys/types.h ) 244and 245.In sys/kernel.h . 246.Sh CONTEXT 247.Fn malloc , 248.Fn realloc 249and 250.Fn reallocf 251may not be called from fast interrupts handlers. 252When called from threaded interrupts, 253.Fa flags 254must contain 255.Dv M_NOWAIT . 256.Pp 257.Fn malloc , 258.Fn realloc 259and 260.Fn reallocf 261may sleep when called with 262.Dv M_WAITOK . 263.Fn free 264never sleeps. 265However, 266.Fn malloc , 267.Fn realloc , 268.Fn reallocf 269and 270.Fn free 271may not be called in a critical section or while holding a spin lock. 272.Pp 273Any calls to 274.Fn malloc 275(even with 276.Dv M_NOWAIT ) 277or 278.Fn free 279when holding a 280.Xr vnode 9 281interlock, will cause a LOR (Lock Order Reversal) due to the 282intertwining of VM Objects and Vnodes. 283.Sh IMPLEMENTATION NOTES 284The memory allocator allocates memory in chunks that have size a power 285of two for requests up to the size of a page of memory. 286For larger requests, one or more pages is allocated. 287While it should not be relied upon, this information may be useful for 288optimizing the efficiency of memory use. 289.Sh RETURN VALUES 290The 291.Fn malloc , 292.Fn realloc , 293and 294.Fn reallocf 295functions return a kernel virtual address that is suitably aligned for 296storage of any type of object, or 297.Dv NULL 298if the request could not be satisfied (implying that 299.Dv M_NOWAIT 300was set). 301.Sh DIAGNOSTICS 302A kernel compiled with the 303.Dv INVARIANTS 304configuration option attempts to detect memory corruption caused by 305such things as writing outside the allocated area and imbalanced calls to the 306.Fn malloc 307and 308.Fn free 309functions. 310Failing consistency checks will cause a panic or a system console 311message. 312.Sh SEE ALSO 313.Xr vmstat 8 , 314.Xr contigmalloc 9 , 315.Xr memguard 9 , 316.Xr vnode 9 317