1.\" $NetBSD: malloc.9,v 1.53 2015/08/07 13:56:48 maxv 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 August 7, 2015 31.Dt MALLOC 9 32.Os 33.Sh NAME 34.Nm malloc , 35.Nm realloc , 36.Nm free , 37.Nm malloc_type_attach , 38.Nm malloc_type_detach , 39.Nm MALLOC_DEFINE , 40.Nm MALLOC_DECLARE 41.Nd general-purpose kernel memory allocator 42.Sh SYNOPSIS 43.In sys/malloc.h 44.Ft void * 45.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" 46.Ft void * 47.Fn realloc "void *addr" "unsigned long newsize" "struct malloc_type *type" \ 48 "int flags" 49.Ft void 50.Fn free "void *addr" "struct malloc_type *type" 51.Ft void 52.Fn malloc_type_attach "struct malloc_type *type" 53.Ft void 54.Fn malloc_type_detach "struct malloc_type *type" 55.In sys/mallocvar.h 56.Fn MALLOC_DEFINE "type" "shortdesc" "longdesc" 57.Fn MALLOC_JUSTDEFINE "type" "shortdesc" "longdesc" 58.Fn MALLOC_DECLARE "type" 59.Sh DESCRIPTION 60.Bf -symbolic 61These interfaces are being obsoleted and their new use is discouraged. 62For new code, use 63.Xr kmem 9 64for variable-sized or one-time allocations and 65.Xr pool_cache 9 66for frequent fixed-size allocations instead. 67.Ef 68.Pp 69The 70.Fn malloc 71function allocates uninitialized memory in kernel address space for an 72object whose size is specified by 73.Fa size . 74.Fn free 75releases memory at address 76.Fa addr 77that was previously allocated by 78.Fn malloc 79for re-use. 80Unlike 81.Xr free 3 , 82.Fn free 83does not accept an 84.Fa addr 85argument that is 86.Dv NULL . 87.Pp 88The 89.Fn realloc 90function changes the size of the previously allocated memory referenced 91by 92.Fa addr 93to 94.Fa size 95and returns a pointer to the 96.Pq possibly moved 97object. 98The memory contents are unchanged up to the lesser of the new 99and old sizes. 100If the new size is larger, the newly allocated memory is 101uninitialized. 102If the requested memory cannot be allocated, 103.Dv NULL 104is returned and the memory referenced by 105.Fa addr 106is unchanged. 107If 108.Fa addr 109is 110.Dv NULL , 111then 112.Fn realloc 113behaves exactly as 114.Fn malloc . 115If the new size is 0, then 116.Fn realloc 117behaves exactly as 118.Fn free . 119.Pp 120Unlike its standard C library counterpart 121.Pq Xr malloc 3 , 122the kernel version takes two more arguments. 123.Pp 124The 125.Fa flags 126argument further qualifies 127.Fn malloc 128operational characteristics as follows: 129.Bl -tag -offset indent -width M_CANFAIL 130.It Dv M_NOWAIT 131Causes 132.Fn malloc 133to return 134.Dv NULL 135if the request cannot be immediately fulfilled due to resource shortage. 136If this flag is not set 137(see 138.Dv M_WAITOK ) , 139.Fn malloc 140will never return 141.Dv NULL . 142.It Dv M_WAITOK 143By default, 144.Fn malloc 145may call 146.Xr cv_wait 9 147to wait for resources to be released by other processes, and this 148flag represents this behaviour. 149Note that 150.Dv M_WAITOK 151is conveniently defined to be 0, and hence may be or'ed into the 152.Fa flags 153argument to indicate that it's ok to wait for resources. 154.It Dv M_ZERO 155Causes the allocated memory to be set to all zeros. 156.It Dv M_CANFAIL 157Changes behaviour for 158.Dv M_WAITOK 159case - if the requested memory size is bigger than 160.Fn malloc 161can ever allocate, return failure, rather than calling 162.Xr panic 9 . 163This is different to M_NOWAIT, since 164the call can still wait for resources. 165.Pp 166Rather than depending on 167.Dv M_CANFAIL , 168kernel code should do proper bound checking itself. 169This flag should only be used in cases where this is not feasible. 170Since it can hide real kernel bugs, its usage is 171.Em strongly discouraged . 172.El 173.Pp 174The 175.Fa type 176argument describes the subsystem and/or use within a subsystem for which 177the allocated memory was needed, and is commonly used to maintain statistics 178about kernel memory usage and, optionally, enforce limits on this usage for 179certain memory types. 180.Pp 181In addition to some built-in generic types defined by the kernel 182memory allocator, subsystems may define their own types. 183.Pp 184The 185.Fn MALLOC_DEFINE 186macro defines a malloc type named 187.Fa type 188with the short description 189.Fa shortdesc , 190which must be a constant string; this description will be used for 191kernel memory statistics reporting. 192The 193.Fa longdesc 194argument, also a constant string, is intended as way to place a 195comment in the actual type definition, and is not currently stored 196in the type structure. 197If kernel memory statistics are being 198gathered, the system will choose a reasonable default limit for 199the malloc type. 200.Pp 201The 202.Fn MALLOC_DECLARE 203macro is intended for use in header files which are included by 204code which needs to use the malloc type, providing the necessary 205extern declaration. 206.Pp 207Code which includes 208\*[Lt]sys/malloc.h\*[Gt] 209does not need to include 210\*[Lt]sys/mallocvar.h\*[Gt] 211to get these macro definitions. 212The 213\*[Lt]sys/mallocvar.h\*[Gt] 214header file is intended for other header files which need to use the 215.Fn MALLOC_DECLARE 216macro. 217.Pp 218The 219.Fn malloc_type_attach 220function attaches the malloc type 221.Fa type 222to the kernel memory allocator. 223.Pp 224The 225.Fn malloc_type_detach 226function detaches the malloc type 227.Fa type 228previously attached with 229.Fn malloc_type_attach . 230.Pp 231The following generic malloc types are currently defined: 232.Pp 233.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 234.It Dv M_DEVBUF 235Device driver memory. 236.It Dv M_DMAMAP 237.Xr bus_dma 9 238structures. 239.It Dv M_FREE 240Should be on free list. 241.It Dv M_PCB 242Protocol control block. 243.It Dv M_SOFTINTR 244Softinterrupt structures. 245.It Dv M_TEMP 246Misc temporary data buffers. 247.El 248.Pp 249Other malloc types are defined by the corresponding subsystem; see the 250documentation for that subsystem for information its available malloc 251types. 252.Sh RETURN VALUES 253.Fn malloc 254returns a kernel virtual address that is suitably aligned for storage of 255any type of object. 256.Sh SEE ALSO 257.Xr vmstat 1 , 258.Xr memoryallocators 9 259