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