1.\" $NetBSD: malloc.9,v 1.49 2014/05/27 17:12:22 wiz Exp $ 2.\" 3.\" Copyright (c) 1996, 2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg, and by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd May 27, 2014 31.Dt MALLOC 9 32.Os 33.Sh NAME 34.Nm malloc , 35.Nm MALLOC , 36.Nm realloc , 37.Nm free , 38.Nm FREE , 39.Nm malloc_roundup , 40.Nm malloc_type_attach , 41.Nm malloc_type_detach , 42.Nm malloc_type_setlimit , 43.Nm MALLOC_DEFINE_LIMIT , 44.Nm MALLOC_DEFINE , 45.Nm MALLOC_DECLARE 46.Nd general-purpose kernel memory allocator 47.Sh SYNOPSIS 48.In sys/malloc.h 49.Ft void * 50.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" 51.Ft void * 52.Fn realloc "void *addr" "unsigned long newsize" "struct malloc_type *type" \ 53 "int flags" 54.Ft void 55.Fn free "void *addr" "struct malloc_type *type" 56.Ft unsigned long 57.Fn malloc_roundup "unsigned long size" 58.Ft void 59.Fn malloc_type_attach "struct malloc_type *type" 60.Ft void 61.Fn malloc_type_detach "struct malloc_type *type" 62.Ft void 63.Fn malloc_type_setlimit "struct malloc_type *type" "unsigned long limit" 64.In sys/mallocvar.h 65.Fn MALLOC_DEFINE_LIMIT "type" "shortdesc" "longdesc" "limit" 66.Fn MALLOC_JUSTDEFINE_LIMIT "type" "shortdesc" "longdesc" "limit" 67.Fn MALLOC_DEFINE "type" "shortdesc" "longdesc" 68.Fn MALLOC_JUSTDEFINE "type" "shortdesc" "longdesc" 69.Fn MALLOC_DECLARE "type" 70.Sh DESCRIPTION 71.Bf -symbolic 72These interfaces are being obsoleted and their new use is discouraged. 73For new code, use 74.Xr kmem 9 75for variable-sized or one-time allocations and 76.Xr pool_cache 9 77for frequent fixed-size allocations instead. 78.Ef 79.Pp 80The 81.Fn malloc 82function allocates uninitialized memory in kernel address space for an 83object whose size is specified by 84.Fa size . 85.Fn malloc_roundup 86returns the actual size of the allocation unit for the given value. 87.Fn free 88releases memory at address 89.Fa addr 90that was previously allocated by 91.Fn malloc 92for re-use. 93Unlike 94.Xr free 3 , 95.Fn free 96does not accept an 97.Fa addr 98argument that is 99.Dv NULL . 100.Pp 101The 102.Fn realloc 103function changes the size of the previously allocated memory referenced 104by 105.Fa addr 106to 107.Fa size 108and returns a pointer to the 109.Pq possibly moved 110object. 111The memory contents are unchanged up to the lesser of the new 112and old sizes. 113If the new size is larger, the newly allocated memory is 114uninitialized. 115If the requested memory cannot be allocated, 116.Dv NULL 117is returned and the memory referenced by 118.Fa addr 119is unchanged. 120If 121.Fa addr 122is 123.Dv NULL , 124then 125.Fn realloc 126behaves exactly as 127.Fn malloc . 128If the new size is 0, then 129.Fn realloc 130behaves exactly as 131.Fn free . 132.Pp 133Unlike its standard C library counterpart 134.Pq Xr malloc 3 , 135the kernel version takes two more arguments. 136.Pp 137The 138.Fa flags 139argument further qualifies 140.Fn malloc 141operational characteristics as follows: 142.Bl -tag -offset indent -width M_CANFAIL 143.It Dv M_NOWAIT 144Causes 145.Fn malloc 146to return 147.Dv NULL 148if the request cannot be immediately fulfilled due to resource shortage. 149If this flag is not set 150(see 151.Dv M_WAITOK ) , 152.Fn malloc 153will never return 154.Dv NULL . 155.It Dv M_WAITOK 156By default, 157.Fn malloc 158may call 159.Xr cv_wait 9 160to wait for resources to be released by other processes, and this 161flag represents this behaviour. 162Note that 163.Dv M_WAITOK 164is conveniently defined to be 0, and hence may be or'ed into the 165.Fa flags 166argument to indicate that it's ok to wait for resources. 167.It Dv M_ZERO 168Causes the allocated memory to be set to all zeros. 169.It Dv M_CANFAIL 170Changes behaviour for 171.Dv M_WAITOK 172case - if the requested memory size is bigger than 173.Fn malloc 174can ever allocate, return failure, rather than calling 175.Xr panic 9 . 176This is different to M_NOWAIT, since 177the call can still wait for resources. 178.Pp 179Rather than depending on 180.Dv M_CANFAIL , 181kernel code should do proper bound checking itself. 182This flag should only be used in cases where this is not feasible. 183Since it can hide real kernel bugs, its usage is 184.Em strongly discouraged . 185.El 186.Pp 187The 188.Fa type 189argument describes the subsystem and/or use within a subsystem for which 190the allocated memory was needed, and is commonly used to maintain statistics 191about kernel memory usage and, optionally, enforce limits on this usage for 192certain memory types. 193.Pp 194In addition to some built-in generic types defined by the kernel 195memory allocator, subsystems may define their own types. 196.Pp 197The 198.Fn MALLOC_DEFINE_LIMIT 199macro defines a malloc type named 200.Fa type 201with the short description 202.Fa shortdesc , 203which must be a constant string; this description will be used for 204kernel memory statistics reporting. 205The 206.Fa longdesc 207argument, also a constant string, is intended as way to place a 208comment in the actual type definition, and is not currently stored 209in the type structure. 210The 211.Fa limit 212argument specifies the maximum amount of memory, in bytes, that this 213malloc type can consume. 214.Pp 215The 216.Fn MALLOC_DEFINE 217macro is equivalent to the 218.Fn MALLOC_DEFINE_LIMIT 219macro with a 220.Fa limit 221argument of 0. 222If kernel memory statistics are being gathered, the system will 223choose a reasonable default limit for the malloc type. 224.Pp 225The 226.Fn MALLOC_DECLARE 227macro is intended for use in header files which are included by 228code which needs to use the malloc type, providing the necessary 229extern declaration. 230.Pp 231Code which includes 232\*[Lt]sys/malloc.h\*[Gt] 233does not need to include 234\*[Lt]sys/mallocvar.h\*[Gt] 235to get these macro definitions. 236The 237\*[Lt]sys/mallocvar.h\*[Gt] 238header file is intended for other header files which need to use the 239.Fn MALLOC_DECLARE 240macro. 241.Pp 242The 243.Fn malloc_type_attach 244function attaches the malloc type 245.Fa type 246to the kernel memory allocator. 247.Pp 248The 249.Fn malloc_type_detach 250function detaches the malloc type 251.Fa type 252previously attached with 253.Fn malloc_type_attach . 254.Pp 255The 256.Fn malloc_type_setlimit 257function sets the memory limit of the malloc type 258.Fa type 259to 260.Fa limit 261bytes. 262The type must already be registered with the kernel memory allocator. 263.Pp 264The following generic malloc types are currently defined: 265.Pp 266.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 267.It Dv M_DEVBUF 268Device driver memory. 269.It Dv M_DMAMAP 270.Xr bus_dma 9 271structures. 272.It Dv M_FREE 273Should be on free list. 274.It Dv M_PCB 275Protocol control block. 276.It Dv M_SOFTINTR 277Softinterrupt structures. 278.It Dv M_TEMP 279Misc temporary data buffers. 280.El 281.Pp 282Other malloc types are defined by the corresponding subsystem; see the 283documentation for that subsystem for information its available malloc 284types. 285.Pp 286Statistics based on the 287.Fa type 288argument are maintained only if the kernel option 289.Dv KMEMSTATS 290is used when compiling the kernel 291.Po 292the default in current 293.Nx 294kernels 295.Pc 296and can be examined by using 297.Sq vmstat -m . 298.Sh RETURN VALUES 299.Fn malloc 300returns a kernel virtual address that is suitably aligned for storage of 301any type of object. 302.Sh DIAGNOSTICS 303A kernel compiled with the 304.Dv DIAGNOSTIC 305configuration option attempts to detect memory corruption caused by 306such things as writing outside the allocated area and imbalanced calls to the 307.Fn malloc 308and 309.Fn free 310functions. 311Failing consistency checks will cause a panic or a system console message: 312.Pp 313.Bl -bullet -offset indent -compact 314.It 315panic: 316.Dq malloc - bogus type 317.It 318panic: 319.Dq malloc: out of space in kmem_map 320.It 321panic: 322.Dq malloc: allocation too large 323.It 324panic: 325.Dq malloc: wrong bucket 326.It 327panic: 328.Dq malloc: lost data 329.It 330panic: 331.Dq free: unaligned addr 332.It 333panic: 334.Dq free: duplicated free 335.It 336panic: 337.Dq free: multiple frees 338.It 339panic: 340.Dq init: minbucket too small/struct freelist too big 341.It 342.Dq multiply freed item Aq addr 343.It 344.Dq Data modified on freelist: Aq data object description 345.El 346.Sh SEE ALSO 347.Xr vmstat 1 , 348.Xr memoryallocators 9 349