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