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 "unsigned long size" "struct malloc_type *type" "int flags"
49 .Fn free "void *addr" "struct malloc_type *type"
51 .Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
53 .Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
54 .Fn MALLOC_DECLARE type
58 .Fn MALLOC_DEFINE type shortdesc longdesc
62 function allocates uninitialized memory in kernel address space for an
63 object whose size is specified by
68 function releases memory at address
70 that was previously allocated by
73 The memory is not zeroed.
84 function changes the size of the previously allocated memory referenced by
89 The contents of the memory are unchanged up to the lesser of the new and
91 Note that the returned value may differ from
93 If the requested memory cannot be allocated,
95 is returned and the memory referenced by
97 is valid and unchanged.
104 function behaves identically to
106 for the specified size.
110 function is identical to
113 will free the passed pointer when the requested memory cannot be allocated.
115 Unlike its standard C library counterpart
117 the kernel version takes two more arguments.
120 argument further qualifies
122 operational characteristics as follows:
123 .Bl -tag -width indent
125 Causes the allocated memory to be set to all zeros.
127 For allocations greater than page size, causes the allocated
128 memory to be excluded from kernel core dumps.
137 if the request cannot be immediately fulfilled due to resource shortage.
140 is required when running in an interrupt context.
142 Indicates that it is OK to wait for resources.
143 If the request cannot be immediately fulfilled, the current process is put
144 to sleep to wait for resources to be released by other processes.
150 functions cannot return
156 Indicates that the system can dig into its reserve in order to obtain the
158 This option used to be called
160 but has been renamed to something more obvious.
161 This option has been deprecated and is slowly being removed from the kernel,
162 and so should not be used with any new programming.
165 Exactly one of either
173 argument is used to perform statistics on memory usage, and for
175 It can be used to identify multiple allocations.
176 The statistics can be examined by
182 .Vt "struct malloc_type"
188 .Bd -literal -offset indent
189 /* sys/something/foo_extern.h */
191 MALLOC_DECLARE(M_FOOBUF);
193 /* sys/something/foo_main.c */
195 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
197 /* sys/something/foo_subr.c */
200 buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT);
212 .Sh IMPLEMENTATION NOTES
213 The memory allocator allocates memory in chunks that have size a power
214 of two for requests up to the size of a page of memory.
215 For larger requests, one or more pages is allocated.
216 While it should not be relied upon, this information may be useful for
217 optimizing the efficiency of memory use.
219 Programmers should be careful not to confuse the malloc flags
234 may not be called from fast interrupts handlers.
235 When called from threaded interrupts,
244 may sleep when called with
257 interlock, will cause a LOR (Lock Order Reversal) due to the
258 intertwining of VM Objects and Vnodes.
265 functions return a kernel virtual address that is suitably aligned for
266 storage of any type of object, or
268 if the request could not be satisfied (implying that
272 A kernel compiled with the
274 configuration option attempts to detect memory corruption caused by
275 such things as writing outside the allocated area and imbalanced calls to the
280 Failing consistency checks will cause a panic or a system console