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 August 4, 2024 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.It Dv M_NEVERFREED 273This is an internal flag used by the 274.Xr UMA 9 275allocator and should not be used in regular 276.Fn malloc 277invocations. 278See the description of VM_ALLOC_NOFREE in 279.Xr vm_page_alloc 9 280for more details. 281.El 282.Pp 283Exactly one of either 284.Dv M_WAITOK 285or 286.Dv M_NOWAIT 287must be specified. 288.Pp 289The 290.Fa type 291argument is used to perform statistics on memory usage, and for 292basic sanity checks. 293It can be used to identify multiple allocations. 294The statistics can be examined by 295.Sq vmstat -m . 296.Pp 297A 298.Fa type 299is defined using 300.Vt "struct malloc_type" 301via the 302.Fn MALLOC_DECLARE 303and 304.Fn MALLOC_DEFINE 305macros. 306.Bd -literal -offset indent 307/* sys/something/foo_extern.h */ 308 309MALLOC_DECLARE(M_FOOBUF); 310 311/* sys/something/foo_main.c */ 312 313MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 314 315/* sys/something/foo_subr.c */ 316 317\&... 318buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT); 319 320.Ed 321.Pp 322In order to use 323.Fn MALLOC_DEFINE , 324one must include 325.In sys/param.h 326(instead of 327.In sys/types.h ) 328and 329.In sys/kernel.h . 330.Sh CONTEXT 331.Fn malloc , 332.Fn realloc 333and 334.Fn reallocf 335may not be called from fast interrupts handlers. 336When called from threaded interrupts, 337.Fa flags 338must contain 339.Dv M_NOWAIT . 340.Pp 341.Fn malloc , 342.Fn realloc 343and 344.Fn reallocf 345may sleep when called with 346.Dv M_WAITOK . 347.Fn free 348never sleeps. 349However, 350.Fn malloc , 351.Fn realloc , 352.Fn reallocf 353and 354.Fn free 355may not be called in a critical section or while holding a spin lock. 356.Pp 357Any calls to 358.Fn malloc 359(even with 360.Dv M_NOWAIT ) 361or 362.Fn free 363when holding a 364.Xr vnode 9 365interlock, will cause a LOR (Lock Order Reversal) due to the 366intertwining of VM Objects and Vnodes. 367.Sh IMPLEMENTATION NOTES 368The memory allocator allocates memory in chunks that have size a power 369of two for requests up to the size of a page of memory. 370For larger requests, one or more pages is allocated. 371While it should not be relied upon, this information may be useful for 372optimizing the efficiency of memory use. 373.Sh RETURN VALUES 374The 375.Fn malloc , 376.Fn realloc , 377and 378.Fn reallocf 379functions return a kernel virtual address that is suitably aligned for 380storage of any type of object, or 381.Dv NULL 382if the request could not be satisfied (implying that 383.Dv M_NOWAIT 384was set). 385.Sh DIAGNOSTICS 386A kernel compiled with the 387.Dv INVARIANTS 388configuration option attempts to detect memory corruption caused by 389such things as writing outside the allocated area and imbalanced calls to the 390.Fn malloc 391and 392.Fn free 393functions. 394Failing consistency checks will cause a panic or a system console 395message. 396.Sh SEE ALSO 397.Xr numa 4 , 398.Xr vmstat 8 , 399.Xr contigmalloc 9 , 400.Xr domainset 9 , 401.Xr memguard 9 , 402.Xr vnode 9 403.Sh HISTORY 404.Fn zfree 405first appeared in 406.Fx 13.0 . 407