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.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the NetBSD 19.\" Foundation, Inc. and its contributors. 20.\" 4. Neither the name of The NetBSD Foundation nor the names of its 21.\" contributors may be used to endorse or promote products derived 22.\" from this software without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 25.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 26.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 27.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 28.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34.\" POSSIBILITY OF SUCH DAMAGE. 35.\" 36.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ 37.\" $FreeBSD: src/share/man/man9/malloc.9,v 1.13.2.6 2002/03/16 02:20:28 archie Exp $ 38.\" $DragonFly: src/share/man/man9/kmalloc.9,v 1.3 2004/03/12 22:29:21 joerg Exp $ 39.\" 40.Dd June 16, 1996 41.Dt MALLOC 9 42.Os 43.Sh NAME 44.Nm malloc , 45.Nm MALLOC , 46.Nm free , 47.Nm FREE 48.Nd kernel memory management routines 49.Sh SYNOPSIS 50.In sys/types.h 51.In sys/malloc.h 52.Ft void * 53.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" 54.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" "int flags" 55.Ft void 56.Fn free "void *addr" "struct malloc_type *type" 57.Fn FREE "void *addr" "struct malloc_type *type" 58.Ft void * 59.Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 60.Ft void * 61.Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 62.Sh DESCRIPTION 63The 64.Fn malloc 65function allocates uninitialized memory in kernel address space for an 66object whose size is specified by 67.Fa size . 68.Pp 69.Fn free 70releases memory at address 71.Fa addr 72that was previously allocated by 73.Fn malloc 74for re-use. 75The memory is not zeroed. 76The kernel implementation of 77.Fn free 78does not allow 79.Fa addr 80to be 81.Dv NULL . 82.Pp 83The 84.Fn realloc 85function changes the size of the previously allocated memory referenced by 86.Fa addr 87to 88.Fa size 89bytes. 90The contents of the memory are unchanged up to the lesser of the new and 91old sizes. 92Note that the returned value may differ from 93.Fa addr . 94If the requested memory cannot be allocated, 95.Dv NULL 96is returned and the memory referenced by 97.Fa addr 98is valid and unchanged. 99If 100.Fa addr 101is 102.Dv NULL , 103the 104.Fn realloc 105function behaves identically to 106.Fn malloc 107for the specified size. 108.Pp 109The 110.Fn reallocf 111function call is identical to the realloc function call, except that it 112will free the passed pointer when the requested memory cannot be allocated. 113.Pp 114The 115.Fn MALLOC 116macro variant is functionally equivalent to 117.Bd -literal -offset indent 118(space) = (cast)malloc((u_long)(size), type, flags) 119.Ed 120.Pp 121and the 122.Fn FREE 123macro variant is equivalent to 124.Bd -literal -offset indent 125free((addr), type) 126.Ed 127.Pp 128Unlike its standard C library counterpart 129.Pq Xr malloc 3 , 130the kernel version takes two more arguments. The 131.Fa flags 132argument further qualifies 133.Fn malloc Ns 's 134operational characteristics as follows: 135.Bl -tag -width indent 136.It Dv M_NOWAIT 137Causes 138.Fn malloc , 139.Fn realloc , 140or 141.Fn reallocf 142to return 143.Dv NULL 144if the request cannot be immediately fulfilled due to resource shortage. 145Otherwise, the current process may be put to sleep to wait for 146resources to be released by other processes. 147If this flag is set, 148.Fn malloc 149will return 150.Dv NULL 151rather then block. 152Note that 153.Dv M_WAITOK 154is defined to be 0, meaning that blocking operation is the default. 155Also note that 156.Dv M_NOWAIT 157is required when running in an interrupt context. 158.It Dv M_ASLEEP 159Causes 160.Fn malloc , 161.Fn realloc , 162or 163.Fn reallocf 164to call 165.Fn asleep 166if the request cannot be immediately fulfilled due to a resource shortage. 167M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow 168the function to call 169.Fn asleep 170and return 171.Dv NULL 172immediately. It is expected that the caller will at some point call 173.Fn await 174and then retry the allocation. Depending on the routine in question, the 175caller may decide to propagate the temporary failure up the call chain 176and actually have some other higher level routine block on the async wait 177that the function queued. 178.It Dv M_WAITOK 179Indicates that it is Ok to wait for resources. It is unconveniently 180defined as 0 so care should be taken never to compare against this value 181directly or try to AND it as a flag. The default operation is to block 182until the memory allocation succeeds. 183.Fn malloc , 184.Fn realloc , 185and 186.Fn reallocf 187can only return 188.Dv NULL 189if 190.Dv M_NOWAIT 191is specified. 192.It Dv M_USE_RESERVE 193Indicates that the system can dig into its reserve in order to obtain the 194requested memory. This option used to be called M_KERNEL but has been 195renamed to something more obvious. This option has been deprecated and is 196slowly being removed from the kernel, and so should not be used with any new 197programming. 198.El 199.Pp 200The 201.Fa type 202argument is used to perform statistics on memory usage, and for 203basic sanity checks. 204The statistics can be examined by 205.Sq vmstat -m . 206.Pp 207A 208.Fa type 209is defined using the 210.Va malloc_type_t 211typedef via the 212.Fn MALLOC_DECLARE 213and 214.Fn MALLOC_DEFINE 215macros. 216.Bd -literal -offset indent 217/* sys/something/foo_extern.h */ 218 219MALLOC_DECLARE(M_FOOBUF); 220 221/* sys/something/foo_main.c */ 222 223MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 224 225/* sys/something/foo_subr.c */ 226 227\&... 228MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT); 229 230.Ed 231.Sh RETURN VALUES 232.Fn malloc , 233.Fn realloc , 234and 235.Fn reallocf 236return a kernel virtual address that is suitably aligned for storage of 237any type of object, or 238.Dv NULL 239if the request could not be satisfied (implying that 240.Dv M_NOWAIT 241was set). 242If 243.Dv M_ASLEEP 244was set and the function returns 245.Dv NULL , 246it will call 247.Fn asleep 248as a side effect. 249.Sh IMPLEMENTATION NOTES 250The memory allocator allocates memory in chunks that have size a power 251of two for requests up to the size of a page of memory. 252For larger requests, one or more pages is allocated. 253While it should not be relied upon, this information may be useful for 254optimizing the efficiency of memory use. 255.Sh SEE ALSO 256.Xr vmstat 8 257.Sh DIAGNOSTICS 258A kernel compiled with the 259.Dv DIAGNOSTIC 260configuration option attempts to detect memory corruption caused by 261such things as writing outside the allocated area and imbalanced calls to the 262.Fn malloc 263and 264.Fn free 265functions. 266Failing consistency checks will cause a panic or a system console 267message: 268.Bl -bullet -offset indent -compact 269.Pp 270.It 271panic: 272.Dq malloc: bogus type 273.It 274panic: 275.Dq malloc: allocation too large 276.It 277panic: 278.Dq malloc: wrong bucket 279.It 280panic: 281.Dq malloc: lost data 282.It 283panic: 284.Dq free: address 0x%x out of range 285.It 286panic: 287.Dq free: type %d out of range 288.It 289panic: 290.Dq free: unaligned addr Aq description of object 291.It 292panic: 293.Dq free: item modified 294.It 295panic: 296.Dq free: multiple free[s] 297.It 298.Dq Data modified on freelist: Aq description of object 299.El 300