307 lines
7.7 KiB
Groff
307 lines
7.7 KiB
Groff
.\"
|
|
.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Paul Kranenburg.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
|
|
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd June 16, 1996
|
|
.Dt MALLOC 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm malloc ,
|
|
.Nm MALLOC ,
|
|
.Nm free ,
|
|
.Nm FREE
|
|
.Nd kernel memory management routines
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sys/malloc.h
|
|
.Ft void *
|
|
.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
|
|
.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" "int flags"
|
|
.Ft void
|
|
.Fn free "void *addr" "struct malloc_type *type"
|
|
.Fn FREE "void *addr" "struct malloc_type *type"
|
|
.Ft void *
|
|
.Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
|
|
.Ft void *
|
|
.Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn malloc
|
|
function allocates uninitialized memory in kernel address space for an
|
|
object whose size is specified by
|
|
.Fa size .
|
|
.Pp
|
|
The
|
|
.Fn free
|
|
function releases memory at address
|
|
.Fa addr
|
|
that was previously allocated by
|
|
.Fn malloc
|
|
for re-use.
|
|
The memory is not zeroed.
|
|
If
|
|
.Fa addr
|
|
is
|
|
.Dv NULL ,
|
|
then
|
|
.Fn free
|
|
does nothing.
|
|
.Pp
|
|
The
|
|
.Fn realloc
|
|
function changes the size of the previously allocated memory referenced by
|
|
.Fa addr
|
|
to
|
|
.Fa size
|
|
bytes.
|
|
The contents of the memory are unchanged up to the lesser of the new and
|
|
old sizes.
|
|
Note that the returned value may differ from
|
|
.Fa addr .
|
|
If the requested memory cannot be allocated,
|
|
.Dv NULL
|
|
is returned and the memory referenced by
|
|
.Fa addr
|
|
is valid and unchanged.
|
|
If
|
|
.Fa addr
|
|
is
|
|
.Dv NULL ,
|
|
the
|
|
.Fn realloc
|
|
function behaves identically to
|
|
.Fn malloc
|
|
for the specified size.
|
|
.Pp
|
|
The
|
|
.Fn reallocf
|
|
function is identical to
|
|
.Fn realloc
|
|
except that it
|
|
will free the passed pointer when the requested memory cannot be allocated.
|
|
.Pp
|
|
The
|
|
.Fn MALLOC
|
|
macro variant is functionally equivalent to
|
|
.Bd -literal -offset indent
|
|
(space) = (cast)malloc((u_long)(size), type, flags)
|
|
.Ed
|
|
.Pp
|
|
and the
|
|
.Fn FREE
|
|
macro variant is equivalent to
|
|
.Bd -literal -offset indent
|
|
free((addr), type)
|
|
.Ed
|
|
.Pp
|
|
Unlike its standard C library counterpart
|
|
.Pq Xr malloc 3 ,
|
|
the kernel version takes two more arguments. The
|
|
.Fa flags
|
|
argument further qualifies
|
|
.Fn malloc Ns 's
|
|
operational characteristics as follows:
|
|
.Bl -tag -width indent
|
|
.It Dv M_ZERO
|
|
Causes the allocated memory to be set to all zeros.
|
|
.It Dv M_NOWAIT
|
|
Causes
|
|
.Fn malloc ,
|
|
.Fn realloc ,
|
|
and
|
|
.Fn reallocf
|
|
to return
|
|
.Dv NULL
|
|
if the request cannot be immediately fulfilled due to resource shortage.
|
|
Otherwise, the current process may be put to sleep to wait for
|
|
resources to be released by other processes.
|
|
If this flag is set,
|
|
.Fn malloc
|
|
will return
|
|
.Dv NULL
|
|
rather than block.
|
|
Note that
|
|
.Dv M_NOWAIT
|
|
is defined to be 0, meaning that blocking operation is the default.
|
|
Also note that
|
|
.Dv M_NOWAIT
|
|
is required when running in an interrupt context.
|
|
.Pp
|
|
Programmers should be careful not to confuse
|
|
.Dv M_NOWAIT ,
|
|
the
|
|
.Fn malloc
|
|
flag, with
|
|
.Dv M_DONTWAIT ,
|
|
an
|
|
.Xr mbuf 9
|
|
allocation flag, which is not a valid argument to
|
|
.Fn malloc .
|
|
.It Dv M_WAITOK
|
|
Indicates that it is Ok to wait for resources. It is unconveniently
|
|
defined as 0 so care should be taken never to compare against this value
|
|
directly or try to AND it as a flag. The default operation is to block
|
|
until the memory allocation succeeds.
|
|
The
|
|
.Fn malloc ,
|
|
.Fn realloc ,
|
|
and
|
|
.Fn reallocf
|
|
functions can only return
|
|
.Dv NULL
|
|
if
|
|
.Dv M_NOWAIT
|
|
is specified.
|
|
.It Dv M_USE_RESERVE
|
|
Indicates that the system can dig into its reserve in order to obtain the
|
|
requested memory. This option used to be called M_KERNEL but has been
|
|
renamed to something more obvious. This option has been deprecated and is
|
|
slowly being removed from the kernel, and so should not be used with any new
|
|
programming.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fa type
|
|
argument is used to perform statistics on memory usage, and for
|
|
basic sanity checks.
|
|
The statistics can be examined by
|
|
.Sq vmstat -m .
|
|
.Pp
|
|
A
|
|
.Fa type
|
|
is defined using the
|
|
.Va malloc_type_t
|
|
typedef via the
|
|
.Fn MALLOC_DECLARE
|
|
and
|
|
.Fn MALLOC_DEFINE
|
|
macros.
|
|
.Bd -literal -offset indent
|
|
/* sys/something/foo_extern.h */
|
|
|
|
MALLOC_DECLARE(M_FOOBUF);
|
|
|
|
/* sys/something/foo_main.c */
|
|
|
|
MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
|
|
|
|
/* sys/something/foo_subr.c */
|
|
|
|
\&...
|
|
MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
|
|
|
|
.Ed
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn malloc ,
|
|
.Fn realloc ,
|
|
and
|
|
.Fn reallocf
|
|
functions return a kernel virtual address that is suitably aligned for
|
|
storage of any type of object, or
|
|
.Dv NULL
|
|
if the request could not be satisfied (implying that
|
|
.Dv M_NOWAIT
|
|
was set).
|
|
.Sh IMPLEMENTATION NOTES
|
|
The memory allocator allocates memory in chunks that have size a power
|
|
of two for requests up to the size of a page of memory.
|
|
For larger requests, one or more pages is allocated.
|
|
While it should not be relied upon, this information may be useful for
|
|
optimizing the efficiency of memory use.
|
|
.Pp
|
|
Malloc flags documented above should
|
|
.Em NOT
|
|
be used with
|
|
.Xr mbuf 9
|
|
routines as it will cause undesired results.
|
|
.Pp
|
|
Any calls to
|
|
.Fn malloc
|
|
or
|
|
.Fn free
|
|
when holding a
|
|
.Xr vnode 9
|
|
interlock, will cause a LOR (Lock Order Reversal) due to the
|
|
interwining of VM Objects and Vnodes.
|
|
.Sh SEE ALSO
|
|
.Xr vmstat 8 ,
|
|
.Xr vnode 9
|
|
.Sh DIAGNOSTICS
|
|
A kernel compiled with the
|
|
.Dv DIAGNOSTIC
|
|
configuration option attempts to detect memory corruption caused by
|
|
such things as writing outside the allocated area and imbalanced calls to the
|
|
.Fn malloc
|
|
and
|
|
.Fn free
|
|
functions.
|
|
Failing consistency checks will cause a panic or a system console
|
|
message:
|
|
.Bl -bullet -offset indent -compact
|
|
.Pp
|
|
.It
|
|
panic:
|
|
.Dq malloc: bogus type
|
|
.It
|
|
panic:
|
|
.Dq malloc: allocation too large
|
|
.It
|
|
panic:
|
|
.Dq malloc: wrong bucket
|
|
.It
|
|
panic:
|
|
.Dq malloc: lost data
|
|
.It
|
|
panic:
|
|
.Dq free: address 0x%x out of range
|
|
.It
|
|
panic:
|
|
.Dq free: type %d out of range
|
|
.It
|
|
panic:
|
|
.Dq free: unaligned addr Aq description of object
|
|
.It
|
|
panic:
|
|
.Dq free: item modified
|
|
.It
|
|
panic:
|
|
.Dq free: multiple free[s]
|
|
.It
|
|
.Dq Data modified on freelist: Aq description of object
|
|
.El
|