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