1.\" $NetBSD: malloc.9,v 1.40 2007/07/30 22:48:47 alc 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 29, 2007 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 81The 82.Fn malloc 83function allocates uninitialized memory in kernel address space for an 84object whose size is specified by 85.Fa size . 86.Fn malloc_roundup 87returns the actual size of the allocation unit for the given value. 88.Fn free 89releases memory at address 90.Fa addr 91that was previously allocated by 92.Fn malloc 93for re-use. 94Unlike 95.Xr free 3 , 96.Fn free 97does not accept an 98.Fa addr 99argument that is 100.Dv NULL . 101.Pp 102The 103.Fn realloc 104function changes the size of the previously allocated memory referenced 105by 106.Fa addr 107to 108.Fa size 109and returns a pointer to the 110.Pq possibly moved 111object. 112The memory contents are unchanged up to the lesser of the new 113and old sizes. 114If the new size is larger, the newly allocated memory is 115uninitialized. 116If the requested memory cannot be allocated, 117.Dv NULL 118is returned and the memory referenced by 119.Fa addr 120is unchanged. 121If 122.Fa addr 123is 124.Dv NULL , 125then 126.Fn realloc 127behaves exactly as 128.Fn malloc . 129If the new size is 0, then 130.Fn realloc 131behaves exactly as 132.Fn free . 133.Pp 134The 135.Fn MALLOC 136macro variant is functionally equivalent to 137.Bd -literal -offset indent 138(space) = (cast)malloc((u_long)(size), type, flags) 139.Ed 140.Pp 141and the 142.Fn FREE 143macro variant is equivalent to 144.Bd -literal -offset indent 145free((void *)(addr), type) 146.Ed 147.Pp 148The 149.Fn MALLOC 150macro is intended to be used with a compile-time constant 151.Fa size 152so that the compiler can do constant folding. 153In the comparison to 154.Fn malloc 155and 156.Fn free 157functions, the 158.Fn MALLOC 159and 160.Fn FREE 161macros may be faster, at the cost of increased code size. 162There is no difference between the memory allocated with MALLOC and malloc. 163i.e., no matter which MALLOC or malloc is used to allocate the memory, 164either FREE or free can be used to free it. 165.Pp 166Unlike its standard C library counterpart 167.Pq Xr malloc 3 , 168the kernel version takes two more arguments. 169.Pp 170The 171.Fa flags 172argument further qualifies 173.Fn malloc 174operational characteristics as follows: 175.Bl -tag -offset indent -width M_CANFAIL 176.It Dv M_NOWAIT 177Causes 178.Fn malloc 179to return 180.Dv NULL 181if the request cannot be immediately fulfilled due to resource shortage. 182If this flag is not set 183(see 184.Dv M_WAITOK ) , 185.Fn malloc 186will never return 187.Dv NULL . 188.It Dv M_WAITOK 189By default, 190.Fn malloc 191may call 192.Xr cv_wait 9 193to wait for resources to be released by other processes, and this 194flag represents this behaviour. 195Note that 196.Dv M_WAITOK 197is conveniently defined to be 0, and hence may be or'ed into the 198.Fa flags 199argument to indicate that it's ok to wait for resources. 200.It Dv M_ZERO 201Causes the allocated memory to be set to all zeros. 202.It Dv M_CANFAIL 203Changes behaviour for 204.Dv M_WAITOK 205case - if the requested memory size is bigger than 206.Fn malloc 207can ever allocate, return failure, rather than calling 208.Xr panic 9 . 209This is different to M_NOWAIT, since 210the call can still wait for resources. 211.Pp 212Rather than depending on 213.Dv M_CANFAIL , 214kernel code should do proper bound checking itself. 215This flag should only be used in cases where this is not feasible. 216Since it can hide real kernel bugs, its usage is 217.Em strongly discouraged . 218.El 219.Pp 220The 221.Fa type 222argument describes the subsystem and/or use within a subsystem for which 223the allocated memory was needed, and is commonly used to maintain statistics 224about kernel memory usage and, optionally, enforce limits on this usage for 225certain memory types. 226.Pp 227In addition to some built-in generic types defined by the kernel 228memory allocator, subsystems may define their own types. 229.Pp 230The 231.Fn MALLOC_DEFINE_LIMIT 232macro defines a malloc type named 233.Fa type 234with the short description 235.Fa shortdesc , 236which must be a constant string; this description will be used for 237kernel memory statistics reporting. 238The 239.Fa longdesc 240argument, also a constant string, is intended as way to place a 241comment in the actual type definition, and is not currently stored 242in the type structure. 243The 244.Fa limit 245argument specifies the maximum amount of memory, in bytes, that this 246malloc type can consume. 247.Pp 248The 249.Fn MALLOC_DEFINE 250macro is equivalent to the 251.Fn MALLOC_DEFINE_LIMIT 252macro with a 253.Fa limit 254argument of 0. 255If kernel memory statistics are being gathered, the system will 256choose a reasonable default limit for the malloc type. 257.Pp 258The 259.Fn MALLOC_DECLARE 260macro is intended for use in header files which are included by 261code which needs to use the malloc type, providing the necessary 262extern declaration. 263.Pp 264Code which includes 265\*[Lt]sys/malloc.h\*[Gt] 266does not need to include 267\*[Lt]sys/mallocvar.h\*[Gt] 268to get these macro definitions. 269The 270\*[Lt]sys/mallocvar.h\*[Gt] 271header file is intended for other header files which need to use the 272.Fn MALLOC_DECLARE 273macro. 274.Pp 275The 276.Fn malloc_type_attach 277function attaches the malloc type 278.Fa type 279to the kernel memory allocator. 280This is intended for use by LKMs; malloc types included in modules 281statically-linked into the kernel are automatically registered with 282the kernel memory allocator. 283However, it is possible to define malloc types without automatically 284registering them using 285.Fn MALLOC_JUSTDEFINE 286or 287.Fn MALLOC_JUSTDEFINE_LIMIT . 288Apart from not automatically registering to the kernel a boot time, 289these functions are equivalent to their counterparts. 290They can be used when a separate LKM codepath for initialization is 291not desired. 292.Pp 293The 294.Fn malloc_type_detach 295function detaches the malloc type 296.Fa type 297previously attached with 298.Fn malloc_type_attach . 299.Pp 300The 301.Fn malloc_type_setlimit 302function sets the memory limit of the malloc type 303.Fa type 304to 305.Fa limit 306bytes. 307The type must already be registered with the kernel memory allocator. 308.Pp 309The following generic malloc types are currently defined: 310.Pp 311.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact 312.It Dv M_DEVBUF 313Device driver memory. 314.It Dv M_DMAMAP 315.Xr bus_dma 9 316structures. 317.It Dv M_FREE 318Should be on free list. 319.It Dv M_PCB 320Protocol control block. 321.It Dv M_SOFTINTR 322Softinterrupt structures. 323.It Dv M_TEMP 324Misc temporary data buffers. 325.El 326.Pp 327Other malloc types are defined by the corresponding subsystem; see the 328documentation for that subsystem for information its available malloc 329types. 330.Pp 331Statistics based on the 332.Fa type 333argument are maintained only if the kernel option 334.Dv KMEMSTATS 335is used when compiling the kernel 336.Po 337the default in current 338.Nx 339kernels 340.Pc 341and can be examined by using 342.Sq vmstat -m . 343.Sh RETURN VALUES 344.Fn malloc 345returns a kernel virtual address that is suitably aligned for storage of 346any type of object. 347.Sh DIAGNOSTICS 348A kernel compiled with the 349.Dv DIAGNOSTIC 350configuration option attempts to detect memory corruption caused by 351such things as writing outside the allocated area and imbalanced calls to the 352.Fn malloc 353and 354.Fn free 355functions. 356Failing consistency checks will cause a panic or a system console message: 357.Bl -bullet -offset indent -compact 358.Pp 359.It 360panic: 361.Dq malloc - bogus type 362.It 363panic: 364.Dq malloc: out of space in kmem_map 365.It 366panic: 367.Dq malloc: allocation too large 368.It 369panic: 370.Dq malloc: wrong bucket 371.It 372panic: 373.Dq malloc: lost data 374.It 375panic: 376.Dq free: unaligned addr 377.It 378panic: 379.Dq free: duplicated free 380.It 381panic: 382.Dq free: multiple frees 383.It 384panic: 385.Dq init: minbucket too small/struct freelist too big 386.It 387.Dq multiply freed item Aq addr 388.It 389.Dq Data modified on freelist: Aq data object description 390.El 391.Sh SEE ALSO 392.Xr vmstat 1 , 393.Xr memoryallocators 9 394