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