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$ 38.\" 39.Dd June 16, 1996 40.Dt MALLOC 9 41.Os 42.Sh NAME 43.Nm malloc , 44.Nm MALLOC , 45.Nm free , 46.Nm FREE 47.Nd kernel memory management routines 48.Sh SYNOPSIS 49.In sys/types.h 50.In sys/malloc.h 51.Ft void * 52.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" 53.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" "int flags" 54.Ft void 55.Fn free "void *addr" "struct malloc_type *type" 56.Fn FREE "void *addr" "struct malloc_type *type" 57.Ft void * 58.Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 59.Ft void * 60.Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 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 68.Fn free 69releases memory at address 70.Fa addr 71that was previously allocated by 72.Fn malloc 73for re-use. 74The memory is not zeroed. 75If 76.Fa addr 77is 78.Dv NULL , 79then 80.Fn free 81does nothing. 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 is identical to 112.Fn realloc 113except that it 114will free the passed pointer when the requested memory cannot be allocated. 115.Pp 116The 117.Fn MALLOC 118macro variant is functionally equivalent to 119.Bd -literal -offset indent 120(space) = (cast)malloc((u_long)(size), type, flags) 121.Ed 122.Pp 123and the 124.Fn FREE 125macro variant is equivalent to 126.Bd -literal -offset indent 127free((addr), type) 128.Ed 129.Pp 130Unlike its standard C library counterpart 131.Pq Xr malloc 3 , 132the kernel version takes two more arguments. The 133.Fa flags 134argument further qualifies 135.Fn malloc Ns 's 136operational characteristics as follows: 137.Bl -tag -width indent 138.It Dv M_ZERO 139Causes the allocated memory to be set to all zeros. 140.It Dv M_NOWAIT 141Causes 142.Fn malloc , 143.Fn realloc , 144and 145.Fn reallocf 146to return 147.Dv NULL 148if the request cannot be immediately fulfilled due to resource shortage. 149Otherwise, the current process may be put to sleep to wait for 150resources to be released by other processes. 151If this flag is set, 152.Fn malloc 153will return 154.Dv NULL 155rather than block. 156Note that 157.Dv M_NOWAIT 158is required when running in an interrupt context. 159.Fn malloc , 160.Fn realloc , 161and 162.Fn reallocf 163can only return 164.Dv NULL 165if 166.Dv M_NOWAIT 167is specified. 168.It Dv M_USE_RESERVE 169Indicates that the system can dig into its reserve in order to obtain the 170requested memory. This option used to be called M_KERNEL but has been 171renamed to something more obvious. This option has been deprecated and is 172slowly being removed from the kernel, and so should not be used with any new 173programming. 174.El 175.Pp 176The 177.Fa type 178argument is used to perform statistics on memory usage, and for 179basic sanity checks. 180The statistics can be examined by 181.Sq vmstat -m . 182.Pp 183A 184.Fa type 185is defined using the 186.Va malloc_type_t 187typedef via the 188.Fn MALLOC_DECLARE 189and 190.Fn MALLOC_DEFINE 191macros. 192.Bd -literal -offset indent 193/* sys/something/foo_extern.h */ 194 195MALLOC_DECLARE(M_FOOBUF); 196 197/* sys/something/foo_main.c */ 198 199MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 200 201/* sys/something/foo_subr.c */ 202 203\&... 204MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT); 205 206.Ed 207.Sh RETURN VALUES 208.Fn malloc , 209.Fn realloc , 210and 211.Fn reallocf 212return a kernel virtual address that is suitably aligned for storage of 213any type of object, or 214.Dv NULL 215if the request could not be satisfied (implying that 216.Dv M_NOWAIT 217was set). 218.Sh IMPLEMENTATION NOTES 219The memory allocator allocates memory in chunks that have size a power 220of two for requests up to the size of a page of memory. 221For larger requests, one or more pages is allocated. 222While it should not be relied upon, this information may be useful for 223optimizing the efficiency of memory use. 224.Pp 225Malloc flags documented above should 226.Em NOT 227be used with 228.Xr mbuf 9 229routines as it will cause undesired results. 230.Pp 231Any calls to 232.Fn malloc 233or 234.Fn free 235when holding a 236.Xr vnode 9 237interlock, will cause a LOR (Lock Order Reversal) due to the 238interwining of VM Objects and Vnodes. 239.Sh SEE ALSO 240.Xr vmstat 8 , 241.Xr vnode 9 242.Sh DIAGNOSTICS 243A kernel compiled with the 244.Dv DIAGNOSTIC 245configuration option attempts to detect memory corruption caused by 246such things as writing outside the allocated area and imbalanced calls to the 247.Fn malloc 248and 249.Fn free 250functions. 251Failing consistency checks will cause a panic or a system console 252message: 253.Bl -bullet -offset indent -compact 254.Pp 255.It 256panic: 257.Dq malloc: bogus type 258.It 259panic: 260.Dq malloc: allocation too large 261.It 262panic: 263.Dq malloc: wrong bucket 264.It 265panic: 266.Dq malloc: lost data 267.It 268panic: 269.Dq free: address 0x%x out of range 270.It 271panic: 272.Dq free: type %d out of range 273.It 274panic: 275.Dq free: unaligned addr Aq description of object 276.It 277panic: 278.Dq free: item modified 279.It 280panic: 281.Dq free: multiple free[s] 282.It 283.Dq Data modified on freelist: Aq description of object 284.El 285