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