1.\" $NetBSD: malloc.9,v 1.55 2018/10/14 17:40:28 jdolecek 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 October 14, 2018 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_NOWAIT 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.El 157.Pp 158The 159.Fa type 160argument describes the subsystem and/or use within a subsystem for which 161the allocated memory was needed, and is commonly used to maintain statistics 162about kernel memory usage and, optionally, enforce limits on this usage for 163certain memory types. 164.Pp 165In addition to some built-in generic types defined by the kernel 166memory allocator, subsystems may define their own types. 167.Pp 168The 169.Fn MALLOC_DEFINE 170macro defines a malloc type named 171.Fa type 172with the short description 173.Fa shortdesc , 174which must be a constant string; this description will be used for 175kernel memory statistics reporting. 176The 177.Fa longdesc 178argument, also a constant string, is intended as way to place a 179comment in the actual type definition, and is not currently stored 180in the type structure. 181If kernel memory statistics are being 182gathered, the system will choose a reasonable default limit for 183the malloc type. 184.Pp 185The 186.Fn MALLOC_DECLARE 187macro is intended for use in header files which are included by 188code which needs to use the malloc type, providing the necessary 189extern declaration. 190.Pp 191Code which includes 192<sys/malloc.h> 193does not need to include 194<sys/mallocvar.h> 195to get these macro definitions. 196The 197<sys/mallocvar.h> 198header file is intended for other header files which need to use the 199.Fn MALLOC_DECLARE 200macro. 201.Pp 202The 203.Fn malloc_type_attach 204function attaches the malloc type 205.Fa type 206to the kernel memory allocator. 207.Pp 208The 209.Fn malloc_type_detach 210function detaches the malloc type 211.Fa type 212previously attached with 213.Fn malloc_type_attach . 214.Pp 215The following generic malloc types are currently defined: 216.Pp 217.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 218.It Dv M_DEVBUF 219Device driver memory. 220.It Dv M_DMAMAP 221.Xr bus_dma 9 222structures. 223.It Dv M_FREE 224Should be on free list. 225.It Dv M_PCB 226Protocol control block. 227.It Dv M_SOFTINTR 228Softinterrupt structures. 229.It Dv M_TEMP 230Misc temporary data buffers. 231.El 232.Pp 233Other malloc types are defined by the corresponding subsystem; see the 234documentation for that subsystem for information its available malloc 235types. 236.Sh RETURN VALUES 237.Fn malloc 238returns a kernel virtual address that is suitably aligned for storage of 239any type of object. 240.Sh SEE ALSO 241.Xr vmstat 1 , 242.Xr memoryallocators 9 243