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