2 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
3 .\" All rights reserved.
5 .\" This code is derived from software contributed to The NetBSD Foundation
6 .\" by Paul Kranenburg.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. All advertising materials mentioning features or use of this software
17 .\" must display the following acknowledgement:
18 .\" This product includes software developed by the NetBSD
19 .\" Foundation, Inc. and its contributors.
20 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
21 .\" contributors may be used to endorse or promote products derived
22 .\" from this software without specific prior written permission.
24 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
25 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
27 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
28 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34 .\" POSSIBILITY OF SUCH DAMAGE.
36 .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
37 .\" $FreeBSD: src/share/man/man9/malloc.9,v 1.13.2.6 2002/03/16 02:20:28 archie Exp $
38 .\" $DragonFly: src/share/man/man9/Attic/malloc.9,v 1.3 2004/03/12 22:29:21 joerg Exp $
48 .Nd kernel memory management routines
53 .Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
54 .Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" "int flags"
56 .Fn free "void *addr" "struct malloc_type *type"
57 .Fn FREE "void *addr" "struct malloc_type *type"
59 .Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
61 .Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
65 function allocates uninitialized memory in kernel address space for an
66 object whose size is specified by
70 releases memory at address
72 that was previously allocated by
75 The memory is not zeroed.
76 The kernel implementation of
85 function changes the size of the previously allocated memory referenced by
90 The contents of the memory are unchanged up to the lesser of the new and
92 Note that the returned value may differ from
94 If the requested memory cannot be allocated,
96 is returned and the memory referenced by
98 is valid and unchanged.
105 function behaves identically to
107 for the specified size.
111 function call is identical to the realloc function call, except that it
112 will free the passed pointer when the requested memory cannot be allocated.
116 macro variant is functionally equivalent to
117 .Bd -literal -offset indent
118 (space) = (cast)malloc((u_long)(size), type, flags)
123 macro variant is equivalent to
124 .Bd -literal -offset indent
128 Unlike its standard C library counterpart
130 the kernel version takes two more arguments. The
132 argument further qualifies
134 operational characteristics as follows:
135 .Bl -tag -width indent
144 if the request cannot be immediately fulfilled due to resource shortage.
145 Otherwise, the current process may be put to sleep to wait for
146 resources to be released by other processes.
154 is defined to be 0, meaning that blocking operation is the default.
157 is required when running in an interrupt context.
166 if the request cannot be immediately fulfilled due to a resource shortage.
167 M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow
172 immediately. It is expected that the caller will at some point call
174 and then retry the allocation. Depending on the routine in question, the
175 caller may decide to propagate the temporary failure up the call chain
176 and actually have some other higher level routine block on the async wait
177 that the function queued.
179 Indicates that it is Ok to wait for resources. It is unconveniently
180 defined as 0 so care should be taken never to compare against this value
181 directly or try to AND it as a flag. The default operation is to block
182 until the memory allocation succeeds.
193 Indicates that the system can dig into its reserve in order to obtain the
194 requested memory. This option used to be called M_KERNEL but has been
195 renamed to something more obvious. This option has been deprecated and is
196 slowly being removed from the kernel, and so should not be used with any new
202 argument is used to perform statistics on memory usage, and for
204 The statistics can be examined by
216 .Bd -literal -offset indent
217 /* sys/something/foo_extern.h */
219 MALLOC_DECLARE(M_FOOBUF);
221 /* sys/something/foo_main.c */
223 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
225 /* sys/something/foo_subr.c */
228 MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
236 return a kernel virtual address that is suitably aligned for storage of
237 any type of object, or
239 if the request could not be satisfied (implying that
244 was set and the function returns
249 .Sh IMPLEMENTATION NOTES
250 The memory allocator allocates memory in chunks that have size a power
251 of two for requests up to the size of a page of memory.
252 For larger requests, one or more pages is allocated.
253 While it should not be relied upon, this information may be useful for
254 optimizing the efficiency of memory use.
258 A kernel compiled with the
260 configuration option attempts to detect memory corruption caused by
261 such things as writing outside the allocated area and imbalanced calls to the
266 Failing consistency checks will cause a panic or a system console
268 .Bl -bullet -offset indent -compact
272 .Dq malloc: bogus type
275 .Dq malloc: allocation too large
278 .Dq malloc: wrong bucket
281 .Dq malloc: lost data
284 .Dq free: address 0x%x out of range
287 .Dq free: type %d out of range
290 .Dq free: unaligned addr Aq description of object
293 .Dq free: item modified
296 .Dq free: multiple free[s]
298 .Dq Data modified on freelist: Aq description of object