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.\" 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.
23.\"
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.
35.\"
36.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
| 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.\" 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.
23.\"
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.
35.\"
36.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
|
37.\" $FreeBSD: head/share/man/man9/malloc.9 177608 2008-03-25 15:44:49Z ru $
| 37.\" $FreeBSD: head/share/man/man9/malloc.9 184205 2008-10-23 15:53:51Z des $
|
38.\"
| 38.\"
|
39.Dd June 12, 2003
| 39.Dd October 23, 2008
|
40.Dt MALLOC 9
41.Os
42.Sh NAME
43.Nm malloc ,
| 40.Dt MALLOC 9
41.Os
42.Sh NAME
43.Nm malloc ,
|
44.Nm MALLOC ,
| |
45.Nm free ,
| 44.Nm free ,
|
46.Nm FREE ,
| |
47.Nm realloc ,
48.Nm reallocf ,
49.Nm MALLOC_DEFINE ,
50.Nm MALLOC_DECLARE
51.Nd kernel memory management routines
52.Sh SYNOPSIS
53.In sys/types.h
54.In sys/malloc.h
55.Ft void *
56.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
| 45.Nm realloc ,
46.Nm reallocf ,
47.Nm MALLOC_DEFINE ,
48.Nm MALLOC_DECLARE
49.Nd kernel memory management routines
50.Sh SYNOPSIS
51.In sys/types.h
52.In sys/malloc.h
53.Ft void *
54.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
|
57.Fn MALLOC space cast "unsigned long size" "struct malloc_type *type" "int flags"
| |
58.Ft void
59.Fn free "void *addr" "struct malloc_type *type"
| 55.Ft void
56.Fn free "void *addr" "struct malloc_type *type"
|
60.Fn FREE "void *addr" "struct malloc_type *type"
| |
61.Ft void *
62.Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
63.Ft void *
64.Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
65.Fn MALLOC_DECLARE type
66.In sys/param.h
67.In sys/malloc.h
68.In sys/kernel.h
69.Fn MALLOC_DEFINE type shortdesc longdesc
70.Sh DESCRIPTION
71The
72.Fn malloc
73function allocates uninitialized memory in kernel address space for an
74object whose size is specified by
75.Fa size .
76.Pp
77The
78.Fn free
79function releases memory at address
80.Fa addr
81that was previously allocated by
82.Fn malloc
83for re-use.
84The memory is not zeroed.
85If
86.Fa addr
87is
88.Dv NULL ,
89then
90.Fn free
91does nothing.
92.Pp
93The
94.Fn realloc
95function changes the size of the previously allocated memory referenced by
96.Fa addr
97to
98.Fa size
99bytes.
100The contents of the memory are unchanged up to the lesser of the new and
101old sizes.
102Note that the returned value may differ from
103.Fa addr .
104If the requested memory cannot be allocated,
105.Dv NULL
106is returned and the memory referenced by
107.Fa addr
108is valid and unchanged.
109If
110.Fa addr
111is
112.Dv NULL ,
113the
114.Fn realloc
115function behaves identically to
116.Fn malloc
117for the specified size.
118.Pp
119The
120.Fn reallocf
121function is identical to
122.Fn realloc
123except that it
124will free the passed pointer when the requested memory cannot be allocated.
125.Pp
| 57.Ft void *
58.Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
59.Ft void *
60.Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
61.Fn MALLOC_DECLARE type
62.In sys/param.h
63.In sys/malloc.h
64.In sys/kernel.h
65.Fn MALLOC_DEFINE type shortdesc longdesc
66.Sh DESCRIPTION
67The
68.Fn malloc
69function allocates uninitialized memory in kernel address space for an
70object whose size is specified by
71.Fa size .
72.Pp
73The
74.Fn free
75function releases memory at address
76.Fa addr
77that was previously allocated by
78.Fn malloc
79for re-use.
80The memory is not zeroed.
81If
82.Fa addr
83is
84.Dv NULL ,
85then
86.Fn free
87does nothing.
88.Pp
89The
90.Fn realloc
91function changes the size of the previously allocated memory referenced by
92.Fa addr
93to
94.Fa size
95bytes.
96The contents of the memory are unchanged up to the lesser of the new and
97old sizes.
98Note that the returned value may differ from
99.Fa addr .
100If the requested memory cannot be allocated,
101.Dv NULL
102is returned and the memory referenced by
103.Fa addr
104is valid and unchanged.
105If
106.Fa addr
107is
108.Dv NULL ,
109the
110.Fn realloc
111function behaves identically to
112.Fn malloc
113for the specified size.
114.Pp
115The
116.Fn reallocf
117function is identical to
118.Fn realloc
119except that it
120will free the passed pointer when the requested memory cannot be allocated.
121.Pp
|
126The
127.Fn MALLOC
128macro variant is functionally equivalent to
129.Bd -literal -offset indent
130(space) = (cast)malloc((u_long)(size), type, flags)
131.Ed
132.Pp
133and the
134.Fn FREE
135macro variant is equivalent to
136.Bd -literal -offset indent
137free((addr), type)
138.Ed
139.Pp
| |
140Unlike its standard C library counterpart
141.Pq Xr malloc 3 ,
142the kernel version takes two more arguments.
143The
144.Fa flags
145argument further qualifies
146.Fn malloc Ns 's
147operational characteristics as follows:
148.Bl -tag -width indent
149.It Dv M_ZERO
150Causes the allocated memory to be set to all zeros.
151.It Dv M_NOWAIT
152Causes
153.Fn malloc ,
154.Fn realloc ,
155and
156.Fn reallocf
157to return
158.Dv NULL
159if the request cannot be immediately fulfilled due to resource shortage.
160Note that
161.Dv M_NOWAIT
162is required when running in an interrupt context.
163.It Dv M_WAITOK
164Indicates that it is OK to wait for resources.
165If the request cannot be immediately fulfilled, the current process is put
166to sleep to wait for resources to be released by other processes.
167The
168.Fn malloc ,
169.Fn realloc ,
170and
171.Fn reallocf
172functions cannot return
173.Dv NULL
174if
175.Dv M_WAITOK
176is specified.
177.It Dv M_USE_RESERVE
178Indicates that the system can dig into its reserve in order to obtain the
179requested memory.
180This option used to be called
181.Dv M_KERNEL
182but has been renamed to something more obvious.
183This option has been deprecated and is slowly being removed from the kernel,
184and so should not be used with any new programming.
185.El
186.Pp
187Exactly one of either
188.Dv M_WAITOK
189or
190.Dv M_NOWAIT
191must be specified.
192.Pp
193The
194.Fa type
195argument is used to perform statistics on memory usage, and for
196basic sanity checks.
197It can be used to identify multiple allocations.
198The statistics can be examined by
199.Sq vmstat -m .
200.Pp
201A
202.Fa type
203is defined using
204.Vt "struct malloc_type"
205via the
206.Fn MALLOC_DECLARE
207and
208.Fn MALLOC_DEFINE
209macros.
210.Bd -literal -offset indent
211/* sys/something/foo_extern.h */
212
213MALLOC_DECLARE(M_FOOBUF);
214
215/* sys/something/foo_main.c */
216
217MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
218
219/* sys/something/foo_subr.c */
220
221\&...
| 122Unlike its standard C library counterpart
123.Pq Xr malloc 3 ,
124the kernel version takes two more arguments.
125The
126.Fa flags
127argument further qualifies
128.Fn malloc Ns 's
129operational characteristics as follows:
130.Bl -tag -width indent
131.It Dv M_ZERO
132Causes the allocated memory to be set to all zeros.
133.It Dv M_NOWAIT
134Causes
135.Fn malloc ,
136.Fn realloc ,
137and
138.Fn reallocf
139to return
140.Dv NULL
141if the request cannot be immediately fulfilled due to resource shortage.
142Note that
143.Dv M_NOWAIT
144is required when running in an interrupt context.
145.It Dv M_WAITOK
146Indicates that it is OK to wait for resources.
147If the request cannot be immediately fulfilled, the current process is put
148to sleep to wait for resources to be released by other processes.
149The
150.Fn malloc ,
151.Fn realloc ,
152and
153.Fn reallocf
154functions cannot return
155.Dv NULL
156if
157.Dv M_WAITOK
158is specified.
159.It Dv M_USE_RESERVE
160Indicates that the system can dig into its reserve in order to obtain the
161requested memory.
162This option used to be called
163.Dv M_KERNEL
164but has been renamed to something more obvious.
165This option has been deprecated and is slowly being removed from the kernel,
166and so should not be used with any new programming.
167.El
168.Pp
169Exactly one of either
170.Dv M_WAITOK
171or
172.Dv M_NOWAIT
173must be specified.
174.Pp
175The
176.Fa type
177argument is used to perform statistics on memory usage, and for
178basic sanity checks.
179It can be used to identify multiple allocations.
180The statistics can be examined by
181.Sq vmstat -m .
182.Pp
183A
184.Fa type
185is defined using
186.Vt "struct malloc_type"
187via the
188.Fn MALLOC_DECLARE
189and
190.Fn MALLOC_DEFINE
191macros.
192.Bd -literal -offset indent
193/* sys/something/foo_extern.h */
194
195MALLOC_DECLARE(M_FOOBUF);
196
197/* sys/something/foo_main.c */
198
199MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
200
201/* sys/something/foo_subr.c */
202
203\&...
|
222MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
| 204buf = malloc(sizeof *buf, M_FOOBUF, M_NOWAIT);
|
223
224.Ed
225.Pp
226In order to use
227.Fn MALLOC_DEFINE ,
228one must include
229.In sys/param.h
230(instead of
231.In sys/types.h )
232and
233.In sys/kernel.h .
234.Sh IMPLEMENTATION NOTES
235The memory allocator allocates memory in chunks that have size a power
236of two for requests up to the size of a page of memory.
237For larger requests, one or more pages is allocated.
238While it should not be relied upon, this information may be useful for
239optimizing the efficiency of memory use.
240.Pp
241Programmers should be careful not to confuse the malloc flags
242.Dv M_NOWAIT
243and
244.Dv M_WAITOK
245with the
246.Xr mbuf 9
247flags
248.Dv M_DONTWAIT
249and
250.Dv M_WAIT .
251.Sh CONTEXT
252.Fn malloc ,
253.Fn realloc
254and
255.Fn reallocf
256may not be called from fast interrupts handlers.
257When called from threaded interrupts,
258.Fa flags
259must contain
260.Dv M_NOWAIT .
261.Pp
262.Fn malloc ,
263.Fn realloc
264and
265.Fn reallocf
266may sleep when called with
267.Dv M_WAITOK .
268.Fn free
269never sleeps.
270.Pp
271Any calls to
272.Fn malloc
273(even with
274.Dv M_NOWAIT )
275or
276.Fn free
277when holding a
278.Xr vnode 9
279interlock, will cause a LOR (Lock Order Reversal) due to the
280intertwining of VM Objects and Vnodes.
281.Sh RETURN VALUES
282The
283.Fn malloc ,
284.Fn realloc ,
285and
286.Fn reallocf
287functions return a kernel virtual address that is suitably aligned for
288storage of any type of object, or
289.Dv NULL
290if the request could not be satisfied (implying that
291.Dv M_NOWAIT
292was set).
293.Sh DIAGNOSTICS
294A kernel compiled with the
295.Dv INVARIANTS
296configuration option attempts to detect memory corruption caused by
297such things as writing outside the allocated area and imbalanced calls to the
298.Fn malloc
299and
300.Fn free
301functions.
302Failing consistency checks will cause a panic or a system console
303message.
304.Sh SEE ALSO
305.Xr vmstat 8 ,
306.Xr contigmalloc 9 ,
307.Xr memguard 9 ,
308.Xr vnode 9
| 205
206.Ed
207.Pp
208In order to use
209.Fn MALLOC_DEFINE ,
210one must include
211.In sys/param.h
212(instead of
213.In sys/types.h )
214and
215.In sys/kernel.h .
216.Sh IMPLEMENTATION NOTES
217The memory allocator allocates memory in chunks that have size a power
218of two for requests up to the size of a page of memory.
219For larger requests, one or more pages is allocated.
220While it should not be relied upon, this information may be useful for
221optimizing the efficiency of memory use.
222.Pp
223Programmers should be careful not to confuse the malloc flags
224.Dv M_NOWAIT
225and
226.Dv M_WAITOK
227with the
228.Xr mbuf 9
229flags
230.Dv M_DONTWAIT
231and
232.Dv M_WAIT .
233.Sh CONTEXT
234.Fn malloc ,
235.Fn realloc
236and
237.Fn reallocf
238may not be called from fast interrupts handlers.
239When called from threaded interrupts,
240.Fa flags
241must contain
242.Dv M_NOWAIT .
243.Pp
244.Fn malloc ,
245.Fn realloc
246and
247.Fn reallocf
248may sleep when called with
249.Dv M_WAITOK .
250.Fn free
251never sleeps.
252.Pp
253Any calls to
254.Fn malloc
255(even with
256.Dv M_NOWAIT )
257or
258.Fn free
259when holding a
260.Xr vnode 9
261interlock, will cause a LOR (Lock Order Reversal) due to the
262intertwining of VM Objects and Vnodes.
263.Sh RETURN VALUES
264The
265.Fn malloc ,
266.Fn realloc ,
267and
268.Fn reallocf
269functions return a kernel virtual address that is suitably aligned for
270storage of any type of object, or
271.Dv NULL
272if the request could not be satisfied (implying that
273.Dv M_NOWAIT
274was set).
275.Sh DIAGNOSTICS
276A kernel compiled with the
277.Dv INVARIANTS
278configuration option attempts to detect memory corruption caused by
279such things as writing outside the allocated area and imbalanced calls to the
280.Fn malloc
281and
282.Fn free
283functions.
284Failing consistency checks will cause a panic or a system console
285message.
286.Sh SEE ALSO
287.Xr vmstat 8 ,
288.Xr contigmalloc 9 ,
289.Xr memguard 9 ,
290.Xr vnode 9
|