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.
17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
20 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
21 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
42 .Nd kernel memory management routines
47 .Fn malloc "size_t size" "struct malloc_type *type" "int flags"
49 .Fn malloc_domain "size_t size" "struct malloc_type *type" "int domain" "int flags"
51 .Fn mallocarray "size_t nmemb" "size_t size" "struct malloc_type *type" "int flags"
53 .Fn free "void *addr" "struct malloc_type *type"
55 .Fn free_domain "void *addr" "struct malloc_type *type"
57 .Fn realloc "void *addr" "size_t size" "struct malloc_type *type" "int flags"
59 .Fn reallocf "void *addr" "size_t size" "struct malloc_type *type" "int flags"
60 .Fn MALLOC_DECLARE type
64 .Fn MALLOC_DEFINE type shortdesc longdesc
68 function allocates uninitialized memory in kernel address space for an
69 object whose size is specified by
74 variant allocates the object from the specified memory domain. Memory allocated
75 with this function should be returned with
78 .Xr numa 9 for more details.
82 function allocates uninitialized memory in kernel address space for an
85 entries whose size is specified by
90 function releases memory at address
92 that was previously allocated by
95 The memory is not zeroed.
106 function changes the size of the previously allocated memory referenced by
111 The contents of the memory are unchanged up to the lesser of the new and
113 Note that the returned value may differ from
115 If the requested memory cannot be allocated,
117 is returned and the memory referenced by
119 is valid and unchanged.
126 function behaves identically to
128 for the specified size.
132 function is identical to
135 will free the passed pointer when the requested memory cannot be allocated.
137 Unlike its standard C library counterpart
139 the kernel version takes two more arguments.
142 argument further qualifies
144 operational characteristics as follows:
145 .Bl -tag -width indent
147 Causes the allocated memory to be set to all zeros.
149 For allocations greater than page size, causes the allocated
150 memory to be excluded from kernel core dumps.
159 if the request cannot be immediately fulfilled due to resource shortage.
162 is required when running in an interrupt context.
164 Indicates that it is OK to wait for resources.
165 If the request cannot be immediately fulfilled, the current process is put
166 to sleep to wait for resources to be released by other processes.
173 functions cannot return
178 If the multiplication of
182 would cause an integer overflow, the
184 function induces a panic.
186 Indicates that the system can use its reserve of memory to satisfy the
188 This option should only be used in combination with
190 when an allocation failure cannot be tolerated by the caller without
191 catastrophic effects on the system.
193 Indicates that the system should allocate executable memory.
194 If this flag is not set, the system will not allocate executable memory.
195 Not all platforms enforce a distinction between executable and
196 non-executable memory.
199 Exactly one of either
207 argument is used to perform statistics on memory usage, and for
209 It can be used to identify multiple allocations.
210 The statistics can be examined by
216 .Vt "struct malloc_type"
222 .Bd -literal -offset indent
223 /* sys/something/foo_extern.h */
225 MALLOC_DECLARE(M_FOOBUF);
227 /* sys/something/foo_main.c */
229 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
231 /* sys/something/foo_subr.c */
234 buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT);
251 may not be called from fast interrupts handlers.
252 When called from threaded interrupts,
261 may sleep when called with
271 may not be called in a critical section or while holding a spin lock.
281 interlock, will cause a LOR (Lock Order Reversal) due to the
282 intertwining of VM Objects and Vnodes.
283 .Sh IMPLEMENTATION NOTES
284 The memory allocator allocates memory in chunks that have size a power
285 of two for requests up to the size of a page of memory.
286 For larger requests, one or more pages is allocated.
287 While it should not be relied upon, this information may be useful for
288 optimizing the efficiency of memory use.
295 functions return a kernel virtual address that is suitably aligned for
296 storage of any type of object, or
298 if the request could not be satisfied (implying that
302 A kernel compiled with the
304 configuration option attempts to detect memory corruption caused by
305 such things as writing outside the allocated area and imbalanced calls to the
310 Failing consistency checks will cause a panic or a system console