.\" $NetBSD: malloc.9,v 1.37 2007/02/17 08:50:05 wiz Exp $ .\" .\" Copyright (c) 1996, 2003 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg, and by Jason R. Thorpe. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the NetBSD .\" Foundation, Inc. and its contributors. .\" 4. Neither the name of The NetBSD Foundation nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd November 7, 2004 .Dt MALLOC 9 .Os .Sh NAME .Nm malloc , .Nm MALLOC , .Nm realloc , .Nm free , .Nm FREE , .Nm malloc_roundup , .Nm malloc_type_attach , .Nm malloc_type_detach , .Nm malloc_type_setlimit , .Nm MALLOC_DEFINE_LIMIT , .Nm MALLOC_DEFINE , .Nm MALLOC_DECLARE .Nd general-purpose kernel memory allocator .Sh SYNOPSIS .In sys/malloc.h .Ft void * .Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" .Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" \ "int flags" .Ft void * .Fn realloc "void *addr" "unsigned long newsize" "struct malloc_type *type" \ "int flags" .Ft void .Fn free "void *addr" "struct malloc_type *type" .Fn FREE "void *addr" "struct malloc_type *type" .Ft unsigned long .Fn malloc_roundup "unsigned long size" .Ft void .Fn malloc_type_attach "struct malloc_type *type" .Ft void .Fn malloc_type_detach "struct malloc_type *type" .Ft void .Fn malloc_type_setlimit "struct malloc_type *type" "unsigned long limit" .In sys/mallocvar.h .Fn MALLOC_DEFINE_LIMIT "type" "shortdesc" "longdesc" "limit" .Fn MALLOC_DEFINE "type" "shortdesc" "longdesc" .Fn MALLOC_DECLARE "type" .Sh DESCRIPTION The .Fn malloc function allocates uninitialized memory in kernel address space for an object whose size is specified by .Fa size . .Fn malloc_roundup returns the actual size of the allocation unit for the given value. .Fn free releases memory at address .Fa addr that was previously allocated by .Fn malloc for re-use. Unlike .Xr free 3 , .Fn free does not accept an .Fa addr argument that is .Dv NULL . .Pp The .Fn realloc function changes the size of the previously allocated memory referenced by .Fa addr to .Fa size and returns a pointer to the .Pq possibly moved object. The memory contents are unchanged up to the lesser of the new and old sizes. If the new size is larger, the newly allocated memory is uninitialized. If the requested memory cannot be allocated, .Dv NULL is returned and the memory referenced by .Fa addr is unchanged. If .Fa addr is .Dv NULL , then .Fn realloc behaves exactly as .Fn malloc . If the new size is 0, then .Fn realloc behaves exactly as .Fn free . .Pp The .Fn MALLOC macro variant is functionally equivalent to .Bd -literal -offset indent (space) = (cast)malloc((u_long)(size), type, flags) .Ed .Pp and the .Fn FREE macro variant is equivalent to .Bd -literal -offset indent free((caddr_t)(addr), type) .Ed .Pp The .Fn MALLOC macro is intended to be used with a compile-time constant .Fa size so that the compiler can do constant folding. In the comparison to .Fn malloc and .Fn free functions, the .Fn MALLOC and .Fn FREE macros may be faster, at the cost of increased code size. There is no difference between the memory allocated with MALLOC and malloc. i.e., no matter which MALLOC or malloc is used to allocate the memory, either FREE or free can be used to free it. .Pp Unlike its standard C library counterpart .Pq Xr malloc 3 , the kernel version takes two more arguments. .Pp The .Fa flags argument further qualifies .Fn malloc operational characteristics as follows: .Bl -tag -offset indent -width M_CANFAIL .It Dv M_NOWAIT Causes .Fn malloc to return .Dv NULL if the request cannot be immediately fulfilled due to resource shortage. If this flag is not set (see .Dv M_WAITOK ) , .Fn malloc will never return .Dv NULL . .It Dv M_WAITOK By default, .Fn malloc may call .Xr tsleep 9 to wait for resources to be released by other processes, and this flag represents this behaviour. Note that .Dv M_WAITOK is conveniently defined to be 0, and hence may be or'ed into the .Fa flags argument to indicate that it's ok to wait for resources. .It Dv M_ZERO Causes the allocated memory to be set to all zeros. .It Dv M_CANFAIL Changes behaviour for .Dv M_WAITOK case - if the requested memory size is bigger than .Fn malloc can ever allocate, return failure, rather than calling .Xr panic 9 . This is different to M_NOWAIT, since the call can still wait for resources. .Pp Rather than depending on .Dv M_CANFAIL , kernel code should do proper bound checking itself. This flag should only be used in cases where this is not feasible. Since it can hide real kernel bugs, its usage is .Em strongly discouraged . .El .Pp The .Fa type argument describes the subsystem and/or use within a subsystem for which the allocated memory was needed, and is commonly used to maintain statistics about kernel memory usage and, optionally, enforce limits on this usage for certain memory types. .Pp In addition to some built-in generic types defined by the kernel memory allocator, subsystems may define their own types. .Pp The .Fn MALLOC_DEFINE_LIMIT macro defines a malloc type named .Fa type with the short description .Fa shortdesc , which must be a constant string; this description will be used for kernel memory statistics reporting. The .Fa longdesc argument, also a constant string, is intended as way to place a comment in the actual type definition, and is not currently stored in the type structure. The .Fa limit argument specifies the maximum amount of memory, in bytes, that this malloc type can consume. .Pp The .Fn MALLOC_DEFINE macro is equivalent to the .Fn MALLOC_DEFINE_LIMIT macro with a .Fa limit argument of 0. If kernel memory statistics are being gathered, the system will choose a reasonable default limit for the malloc type. .Pp The .Fn MALLOC_DECLARE macro is intended for use in header files which are included by code which needs to use the malloc type, providing the necessary extern declaration. .Pp Code which includes \*[Lt]sys/malloc.h\*[Gt] does not need to include \*[Lt]sys/mallocvar.h\*[Gt] to get these macro definitions. The \*[Lt]sys/mallocvar.h\*[Gt] header file is intended for other header files which need to use the .Fn MALLOC_DECLARE macro. .Pp The .Fn malloc_type_attach function attaches the malloc type .Fa type to the kernel memory allocator. This is intended for use by LKMs; malloc types included in modules statically-linked into the kernel are automatically registered with the kernel memory allocator. .Pp The .Fn malloc_type_detach function detaches the malloc type .Fa type previously attached with .Fn malloc_type_attach . .Pp The .Fn malloc_type_setlimit function sets the memory limit of the malloc type .Fa type to .Fa limit bytes. The type must already be registered with the kernel memory allocator. .Pp The following generic malloc types are currently defined: .Pp .Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact .It Dv M_DEVBUF Device driver memory. .It Dv M_DMAMAP .Xr bus_dma 9 structures. .It Dv M_FREE Should be on free list. .It Dv M_PCB Protocol control block. .It Dv M_SOFTINTR Softinterrupt structures. .It Dv M_TEMP Misc temporary data buffers. .El .Pp Other malloc types are defined by the corresponding subsystem; see the documentation for that subsystem for information its available malloc types. .Pp Statistics based on the .Fa type argument are maintained only if the kernel option .Dv KMEMSTATS is used when compiling the kernel .Po the default in current .Nx kernels .Pc and can be examined by using .Sq vmstat -m . .Sh RETURN VALUES .Fn malloc returns a kernel virtual address that is suitably aligned for storage of any type of object. .Sh DIAGNOSTICS A kernel compiled with the .Dv DIAGNOSTIC configuration option attempts to detect memory corruption caused by such things as writing outside the allocated area and imbalanced calls to the .Fn malloc and .Fn free functions. Failing consistency checks will cause a panic or a system console message: .Bl -bullet -offset indent -compact .Pp .It panic: .Dq malloc - bogus type .It panic: .Dq malloc: out of space in kmem_map .It panic: .Dq malloc: allocation too large .It panic: .Dq malloc: wrong bucket .It panic: .Dq malloc: lost data .It panic: .Dq free: unaligned addr .It panic: .Dq free: duplicated free .It panic: .Dq free: multiple frees .It panic: .Dq init: minbucket too small/struct freelist too big .It .Dq multiply freed item Aq addr .It .Dq Data modified on freelist: Aq data object description .El .Sh SEE ALSO .Xr vmstat 1 , .Xr memoryallocators 9