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 November 19, 2015 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 "unsigned long 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" "unsigned long size" "struct malloc_type *type" "int flags" 54.Ft void * 55.Fn reallocf "void *addr" "unsigned long 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 realloc , 158and 159.Fn reallocf 160functions cannot return 161.Dv NULL 162if 163.Dv M_WAITOK 164is specified. 165The 166.Fn mallocarray 167function can return 168.Dv NULL 169if the multiplication of 170.Fa nmemb 171and 172.Fa size 173would cause an integer overflow. 174.It Dv M_USE_RESERVE 175Indicates that the system can use its reserve of memory to satisfy the 176request. 177This option should only be used in combination with 178.Dv M_NOWAIT 179when an allocation failure cannot be tolerated by the caller without 180catastrophic effects on the system. 181.El 182.Pp 183Exactly one of either 184.Dv M_WAITOK 185or 186.Dv M_NOWAIT 187must be specified. 188.Pp 189The 190.Fa type 191argument is used to perform statistics on memory usage, and for 192basic sanity checks. 193It can be used to identify multiple allocations. 194The statistics can be examined by 195.Sq vmstat -m . 196.Pp 197A 198.Fa type 199is defined using 200.Vt "struct malloc_type" 201via the 202.Fn MALLOC_DECLARE 203and 204.Fn MALLOC_DEFINE 205macros. 206.Bd -literal -offset indent 207/* sys/something/foo_extern.h */ 208 209MALLOC_DECLARE(M_FOOBUF); 210 211/* sys/something/foo_main.c */ 212 213MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 214 215/* sys/something/foo_subr.c */ 216 217\&... 218buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT); 219 220.Ed 221.Pp 222In order to use 223.Fn MALLOC_DEFINE , 224one must include 225.In sys/param.h 226(instead of 227.In sys/types.h ) 228and 229.In sys/kernel.h . 230.Sh CONTEXT 231.Fn malloc , 232.Fn realloc 233and 234.Fn reallocf 235may not be called from fast interrupts handlers. 236When called from threaded interrupts, 237.Fa flags 238must contain 239.Dv M_NOWAIT . 240.Pp 241.Fn malloc , 242.Fn realloc 243and 244.Fn reallocf 245may sleep when called with 246.Dv M_WAITOK . 247.Fn free 248never sleeps. 249However, 250.Fn malloc , 251.Fn realloc , 252.Fn reallocf 253and 254.Fn free 255may not be called in a critical section or while holding a spin lock. 256.Pp 257Any calls to 258.Fn malloc 259(even with 260.Dv M_NOWAIT ) 261or 262.Fn free 263when holding a 264.Xr vnode 9 265interlock, will cause a LOR (Lock Order Reversal) due to the 266intertwining of VM Objects and Vnodes. 267.Sh IMPLEMENTATION NOTES 268The memory allocator allocates memory in chunks that have size a power 269of two for requests up to the size of a page of memory. 270For larger requests, one or more pages is allocated. 271While it should not be relied upon, this information may be useful for 272optimizing the efficiency of memory use. 273.Sh RETURN VALUES 274The 275.Fn malloc , 276.Fn realloc , 277and 278.Fn reallocf 279functions return a kernel virtual address that is suitably aligned for 280storage of any type of object, or 281.Dv NULL 282if the request could not be satisfied (implying that 283.Dv M_NOWAIT 284was set). 285.Sh DIAGNOSTICS 286A kernel compiled with the 287.Dv INVARIANTS 288configuration option attempts to detect memory corruption caused by 289such things as writing outside the allocated area and imbalanced calls to the 290.Fn malloc 291and 292.Fn free 293functions. 294Failing consistency checks will cause a panic or a system console 295message. 296.Sh SEE ALSO 297.Xr vmstat 8 , 298.Xr contigmalloc 9 , 299.Xr memguard 9 , 300.Xr vnode 9 301