/share/man/man9/malloc.9

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