xref: /freebsd/share/man/man9/malloc.9 (revision cfd6422a5217410fbd66f7a7a8a64d9d85e61229)
1.\"
2.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
3.\" All rights reserved.
4.\"
5.\" This code is derived from software contributed to The NetBSD Foundation
6.\" by Paul Kranenburg.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
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.\"
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.
28.\"
29.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
30.\" $FreeBSD$
31.\"
32.Dd October 30, 2020
33.Dt MALLOC 9
34.Os
35.Sh NAME
36.Nm malloc ,
37.Nm free ,
38.Nm realloc ,
39.Nm reallocf ,
40.Nm MALLOC_DEFINE ,
41.Nm MALLOC_DECLARE
42.Nd kernel memory management routines
43.Sh SYNOPSIS
44.In sys/types.h
45.In sys/malloc.h
46.Ft void *
47.Fn malloc "size_t size" "struct malloc_type *type" "int flags"
48.Ft void *
49.Fn mallocarray "size_t nmemb" "size_t size" "struct malloc_type *type" "int flags"
50.Ft void
51.Fn free "void *addr" "struct malloc_type *type"
52.Ft void
53.Fn zfree "void *addr" "struct malloc_type *type"
54.Ft void *
55.Fn realloc "void *addr" "size_t size" "struct malloc_type *type" "int flags"
56.Ft void *
57.Fn reallocf "void *addr" "size_t size" "struct malloc_type *type" "int flags"
58.Ft size_t
59.Fn malloc_usable_size "const void *addr"
60.Ft void *
61.Fn malloc_exec "size_t size" "struct malloc_type *type" "int flags"
62.Fn MALLOC_DECLARE type
63.In sys/param.h
64.In sys/malloc.h
65.In sys/kernel.h
66.Fn MALLOC_DEFINE type shortdesc longdesc
67.In sys/param.h
68.In sys/domainset.h
69.Ft void *
70.Fn malloc_domainset "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
71.Ft void *
72.Fn malloc_domainset_exec "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
73.Sh DESCRIPTION
74The
75.Fn malloc
76function allocates uninitialized memory in kernel address space for an
77object whose size is specified by
78.Fa size .
79.Pp
80The
81.Fn malloc_domainset
82variant allocates memory from a specific
83.Xr numa 4
84domain using the specified domain selection policy.
85See
86.Xr domainset 9
87for some example policies.
88.Pp
89Both
90.Fn malloc_exec
91and
92.Fn malloc_domainset_exec
93can be used to return executable memory.
94Not all platforms enforce a distinction between executable and non-executable memory.
95.Pp
96The
97.Fn mallocarray
98function allocates uninitialized memory in kernel address space for an
99array of
100.Fa nmemb
101entries whose size is specified by
102.Fa size .
103.Pp
104The
105.Fn free
106function releases memory at address
107.Fa addr
108that was previously allocated by
109.Fn malloc
110for re-use.
111The memory is not zeroed.
112If
113.Fa addr
114is
115.Dv NULL ,
116then
117.Fn free
118does nothing.
119.Pp
120Like
121.Fn free ,
122the
123.Fn zfree
124function releases memory at address
125.Fa addr
126that was previously allocated by
127.Fn malloc
128for re-use.
129However,
130.Fn zfree
131will zero the memory before it is released.
132.Pp
133The
134.Fn realloc
135function changes the size of the previously allocated memory referenced by
136.Fa addr
137to
138.Fa size
139bytes.
140The contents of the memory are unchanged up to the lesser of the new and
141old sizes.
142Note that the returned value may differ from
143.Fa addr .
144If the requested memory cannot be allocated,
145.Dv NULL
146is returned and the memory referenced by
147.Fa addr
148is valid and unchanged.
149If
150.Fa addr
151is
152.Dv NULL ,
153the
154.Fn realloc
155function behaves identically to
156.Fn malloc
157for the specified size.
158.Pp
159The
160.Fn reallocf
161function is identical to
162.Fn realloc
163except that it
164will free the passed pointer when the requested memory cannot be allocated.
165.Pp
166The
167.Fn malloc_usable_size
168function returns the usable size of the allocation pointed to by
169.Fa addr .
170The return value may be larger than the size that was requested during
171allocation.
172.Pp
173Unlike its standard C library counterpart
174.Pq Xr malloc 3 ,
175the kernel version takes two more arguments.
176The
177.Fa flags
178argument further qualifies
179.Fn malloc Ns 's
180operational characteristics as follows:
181.Bl -tag -width indent
182.It Dv M_ZERO
183Causes the allocated memory to be set to all zeros.
184.It Dv M_NODUMP
185For allocations greater than page size, causes the allocated
186memory to be excluded from kernel core dumps.
187.It Dv M_NOWAIT
188Causes
189.Fn malloc ,
190.Fn realloc ,
191and
192.Fn reallocf
193to return
194.Dv NULL
195if the request cannot be immediately fulfilled due to resource shortage.
196Note that
197.Dv M_NOWAIT
198is required when running in an interrupt context.
199.It Dv M_WAITOK
200Indicates that it is OK to wait for resources.
201If the request cannot be immediately fulfilled, the current process is put
202to sleep to wait for resources to be released by other processes.
203The
204.Fn malloc ,
205.Fn mallocarray ,
206.Fn realloc ,
207and
208.Fn reallocf
209functions cannot return
210.Dv NULL
211if
212.Dv M_WAITOK
213is specified.
214If the multiplication of
215.Fa nmemb
216and
217.Fa size
218would cause an integer overflow, the
219.Fn mallocarray
220function induces a panic.
221.It Dv M_USE_RESERVE
222Indicates that the system can use its reserve of memory to satisfy the
223request.
224This option should only be used in combination with
225.Dv M_NOWAIT
226when an allocation failure cannot be tolerated by the caller without
227catastrophic effects on the system.
228.El
229.Pp
230Exactly one of either
231.Dv M_WAITOK
232or
233.Dv M_NOWAIT
234must be specified.
235.Pp
236The
237.Fa type
238argument is used to perform statistics on memory usage, and for
239basic sanity checks.
240It can be used to identify multiple allocations.
241The statistics can be examined by
242.Sq vmstat -m .
243.Pp
244A
245.Fa type
246is defined using
247.Vt "struct malloc_type"
248via the
249.Fn MALLOC_DECLARE
250and
251.Fn MALLOC_DEFINE
252macros.
253.Bd -literal -offset indent
254/* sys/something/foo_extern.h */
255
256MALLOC_DECLARE(M_FOOBUF);
257
258/* sys/something/foo_main.c */
259
260MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
261
262/* sys/something/foo_subr.c */
263
264\&...
265buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT);
266
267.Ed
268.Pp
269In order to use
270.Fn MALLOC_DEFINE ,
271one must include
272.In sys/param.h
273(instead of
274.In sys/types.h )
275and
276.In sys/kernel.h .
277.Sh CONTEXT
278.Fn malloc ,
279.Fn realloc
280and
281.Fn reallocf
282may not be called from fast interrupts handlers.
283When called from threaded interrupts,
284.Fa flags
285must contain
286.Dv M_NOWAIT .
287.Pp
288.Fn malloc ,
289.Fn realloc
290and
291.Fn reallocf
292may sleep when called with
293.Dv M_WAITOK .
294.Fn free
295never sleeps.
296However,
297.Fn malloc ,
298.Fn realloc ,
299.Fn reallocf
300and
301.Fn free
302may not be called in a critical section or while holding a spin lock.
303.Pp
304Any calls to
305.Fn malloc
306(even with
307.Dv M_NOWAIT )
308or
309.Fn free
310when holding a
311.Xr vnode 9
312interlock, will cause a LOR (Lock Order Reversal) due to the
313intertwining of VM Objects and Vnodes.
314.Sh IMPLEMENTATION NOTES
315The memory allocator allocates memory in chunks that have size a power
316of two for requests up to the size of a page of memory.
317For larger requests, one or more pages is allocated.
318While it should not be relied upon, this information may be useful for
319optimizing the efficiency of memory use.
320.Sh RETURN VALUES
321The
322.Fn malloc ,
323.Fn realloc ,
324and
325.Fn reallocf
326functions return a kernel virtual address that is suitably aligned for
327storage of any type of object, or
328.Dv NULL
329if the request could not be satisfied (implying that
330.Dv M_NOWAIT
331was set).
332.Sh DIAGNOSTICS
333A kernel compiled with the
334.Dv INVARIANTS
335configuration option attempts to detect memory corruption caused by
336such things as writing outside the allocated area and imbalanced calls to the
337.Fn malloc
338and
339.Fn free
340functions.
341Failing consistency checks will cause a panic or a system console
342message.
343.Sh SEE ALSO
344.Xr numa 4 ,
345.Xr vmstat 8 ,
346.Xr contigmalloc 9 ,
347.Xr domainset 9 ,
348.Xr memguard 9 ,
349.Xr vnode 9
350