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