xref: /freebsd/share/man/man9/malloc.9 (revision a1a4f1a0d87b594d3f17a97dc0127eec1417e6f6)
1.\"	$NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
2.\"
3.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Paul Kranenburg.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. All advertising materials mentioning features or use of this software
18.\"    must display the following acknowledgement:
19.\"        This product includes software developed by the NetBSD
20.\"        Foundation, Inc. and its contributors.
21.\" 4. Neither the name of The NetBSD Foundation nor the names of its
22.\"    contributors may be used to endorse or promote products derived
23.\"    from this software without specific prior written permission.
24.\"
25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
29.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35.\" POSSIBILITY OF SUCH DAMAGE.
36.\"
37.\" $FreeBSD$
38.\"
39.Dd June 16, 1996
40.Dt MALLOC 9
41.Os FreeBSD
42.Sh NAME
43.Nm malloc ,
44.Nm MALLOC ,
45.Nm free ,
46.Nm FREE
47.Nd kernel memory management routines
48.Sh SYNOPSIS
49.Fd #include <sys/types.h>
50.Fd #include <sys/malloc.h>
51.Ft void *
52.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
53.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type  *type" "int flags"
54.Ft void
55.Fn free "void *addr" "struct malloc_type *type"
56.Fn FREE "void *addr" "struct malloc_type *type"
57.Sh DESCRIPTION
58The
59.Fn malloc
60function allocates uninitialized memory in kernel address space for an
61object whose size is specified by
62.Fa size .
63.Fn free
64releases memory at address
65.Fa addr
66that was previously allocated by
67.Fn malloc
68for re-use.
69The
70.Fn MALLOC
71macro variant is functionally equivalent to
72.Bd -literal -offset indent
73(space) = (cast)malloc((u_long)(size), type, flags)
74.Ed
75.Pp
76and the
77.Fn FREE
78macro variant is equivalent to
79.Bd -literal -offset indent
80free((addr), type)
81.Ed
82.Pp
83Unlike its standard C library counterpart
84.Pq Xr malloc 3 ,
85the kernel version takes two more arguments.  The
86.Fa flags
87argument further qualifies
88.Fn malloc No Ns 's
89operational characteristics as follows:
90.Bl -tag -width indent
91.It Dv M_NOWAIT
92Causes
93.Fn malloc
94to return
95.Dv NULL
96if the request cannot be immediately fulfilled due to resource shortage.
97Otherwise,
98.Fn malloc
99may call sleep to wait for resources to be released by other processes.
100If this flag is set,
101.Fn malloc
102will return
103.Dv NULL
104rather then block.  Note that
105.Dv M_WAITOK
106is defined to be 0, meaning that blocking operation is the default.
107.It Dv M_ASLEEP
108Causes
109.Fn malloc
110to call
111.Fn asleep
112if the request cannot be immediately fulfilled due to a resource shortage.
113M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow
114malloc to call
115.Fn asleep
116and return
117.Dv NULL
118immediately.  It is expected that the caller will at some point call
119.Fn await
120and then retry the allocation.  Depending on the routine in question, the
121caller may decide to propagate the temporary failure up the call chain
122and actually have some other higher level routine block on the async wait
123that
124.Fn malloc
125queued.
126.It Dv M_WAITOK
127indicates that it is Ok to wait for resources.  It is unconveniently
128defined as 0 so care should be taken never to compare against this value
129directly or try to AND it as a flag.  The default operation is to block
130until the memory allocation succeeds.
131.Fn malloc
132can only return
133.Dv NULL
134if
135.Dv M_NOWAIT
136is specified.
137.El
138.Pp
139The
140.Fa type
141argument is used to perform statistics on memory usage, and for
142basic sanity checks.
143The statistics can be examined by
144.Sq vmstat -m .
145.Pp
146A
147.Fa type
148is defined using the
149.Va malloc_type_t
150typedef like this:
151.Bd -literal -offset indent
152/* sys/something/foo_extern.h */
153
154extern malloc_type_t M_FOOBUF;
155
156/* sys/something/foo_main.c */
157
158malloc_type_t M_FOOBUF = {
159	"Foo Buffers",
160	"Buffers for foo data in transit to the InfImpDrive"
161};
162
163/* sys/something/foo_subr.c */
164
165...
166MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
167
168.Ed
169.Sh RETURN VALUES
170.Fn malloc
171returns a kernel virtual address that is suitably aligned for storage of
172any type of object, or
173.Dv NULL
174if the request could not be satisfied and
175.Dv M_NOWAIT
176was set.  If
177.Dv M_ASLEEP
178was set and
179.Fn malloc
180returns
181.Dv NULL ,
182it will call
183.Fn asleep
184as a side effect.
185.Sh SEE ALSO
186.Xr vmstat 8
187.Sh DIAGNOSTICS
188A kernel compiled with the
189.Dv DIAGNOSTIC
190configuration option attempts to detect memory corruption caused by
191such things as writing outside the allocated area and imbalanced calls to the
192.Fn malloc
193and
194.Fn free
195functions. Failing consistency checks will cause a panic or a system console
196message:
197.Bl -bullet -offset indent -compact
198.Pp
199.It
200panic:
201.Dq malloc: bogus type
202.It
203panic:
204.Dq malloc: allocation too large
205.It
206panic:
207.Dq malloc: wrong bucket
208.It
209panic:
210.Dq malloc: lost data
211.It
212panic:
213.Dq free: address 0x%x out of range
214.It
215panic:
216.Dq free: type %d out of range
217.It
218panic:
219.Dq free: unaligned addr Aq description of object
220.It
221panic:
222.Dq free: item modified
223.It
224panic:
225.Dq free: multiple free[s]
226.It
227.Dq Data modified on freelist: Aq description of object
228.El
229