1111b49c35
of the typeset output, tend to make diffs harder to read and provide bad examples for new-comers to mdoc.
237 lines
6.5 KiB
Groff
237 lines
6.5 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 FreeBSD
|
|
.Sh NAME
|
|
.Nm malloc ,
|
|
.Nm MALLOC ,
|
|
.Nm free ,
|
|
.Nm FREE
|
|
.Nd kernel memory management routines
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <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"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn malloc
|
|
function allocates uninitialized memory in kernel address space for an
|
|
object whose size is specified by
|
|
.Fa size .
|
|
.Fn free
|
|
releases memory at address
|
|
.Fa addr
|
|
that was previously allocated by
|
|
.Fn malloc
|
|
for re-use. The memory is not zeroed.
|
|
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 No Ns 's
|
|
operational characteristics as follows:
|
|
.Bl -tag -width indent
|
|
.It Dv M_NOWAIT
|
|
Causes
|
|
.Fn malloc
|
|
to return
|
|
.Dv NULL
|
|
if the request cannot be immediately fulfilled due to resource shortage.
|
|
Otherwise,
|
|
.Fn malloc
|
|
may call sleep to wait for resources to be released by other processes.
|
|
If this flag is set,
|
|
.Fn malloc
|
|
will return
|
|
.Dv NULL
|
|
rather then block. Note that
|
|
.Dv M_WAITOK
|
|
is defined to be 0, meaning that blocking operation is the default.
|
|
.It Dv M_ASLEEP
|
|
Causes
|
|
.Fn malloc
|
|
to call
|
|
.Fn asleep
|
|
if the request cannot be immediately fulfilled due to a resource shortage.
|
|
M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow
|
|
malloc to call
|
|
.Fn asleep
|
|
and return
|
|
.Dv NULL
|
|
immediately. It is expected that the caller will at some point call
|
|
.Fn await
|
|
and then retry the allocation. Depending on the routine in question, the
|
|
caller may decide to propagate the temporary failure up the call chain
|
|
and actually have some other higher level routine block on the async wait
|
|
that
|
|
.Fn malloc
|
|
queued.
|
|
.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.
|
|
.Fn malloc
|
|
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 depreciated 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
|
|
.Fn malloc
|
|
returns 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 and
|
|
.Dv M_NOWAIT
|
|
was set. If
|
|
.Dv M_ASLEEP
|
|
was set and
|
|
.Fn malloc
|
|
returns
|
|
.Dv NULL ,
|
|
it will call
|
|
.Fn asleep
|
|
as a side effect.
|
|
.Sh SEE ALSO
|
|
.Xr vmstat 8
|
|
.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
|