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