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