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