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