255 lines
6.6 KiB
Groff
255 lines
6.6 KiB
Groff
.\" $NetBSD: malloc.9,v 1.59 2021/01/04 18:27:46 pgoyette Exp $
|
|
.\"
|
|
.\" Copyright (c) 1996, 2003 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Paul Kranenburg, and by Jason R. Thorpe.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" 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 FOUNDATION 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.
|
|
.\"
|
|
.Dd January 4, 2021
|
|
.Dt MALLOC 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm malloc ,
|
|
.Nm realloc ,
|
|
.Nm free ,
|
|
.Nm malloc_type_attach ,
|
|
.Nm malloc_type_detach ,
|
|
.Nm MALLOC_DEFINE ,
|
|
.Nm MALLOC_DECLARE
|
|
.Nd general-purpose kernel memory allocator
|
|
.Sh SYNOPSIS
|
|
.In sys/malloc.h
|
|
.Ft void *
|
|
.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
|
|
.Ft void *
|
|
.Fn realloc "void *addr" "unsigned long newsize" "struct malloc_type *type" \
|
|
"int flags"
|
|
.Ft void
|
|
.Fn free "void *addr" "struct malloc_type *type"
|
|
.Ft void
|
|
.Fn malloc_type_attach "struct malloc_type *type"
|
|
.Ft void
|
|
.Fn malloc_type_detach "struct malloc_type *type"
|
|
.In sys/mallocvar.h
|
|
.Fn MALLOC_DEFINE "type" "shortdesc" "longdesc"
|
|
.Fn MALLOC_JUSTDEFINE "type" "shortdesc" "longdesc"
|
|
.Fn MALLOC_DECLARE "type"
|
|
.Sh DESCRIPTION
|
|
.Bf -symbolic
|
|
These interfaces are being obsoleted and their new use is discouraged.
|
|
For new code, use
|
|
.Xr kmem 9
|
|
for variable-sized or one-time allocations and
|
|
.Xr pool_cache 9
|
|
for frequent fixed-size allocations instead.
|
|
.Ef
|
|
.Pp
|
|
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.
|
|
Unlike
|
|
.Xr free 3 ,
|
|
.Fn free
|
|
does not accept an
|
|
.Fa addr
|
|
argument that is
|
|
.Dv NULL .
|
|
.Pp
|
|
The
|
|
.Fn realloc
|
|
function changes the size of the previously allocated memory referenced
|
|
by
|
|
.Fa addr
|
|
to
|
|
.Fa size
|
|
and returns a pointer to the
|
|
.Pq possibly moved
|
|
object.
|
|
The memory contents are unchanged up to the lesser of the new
|
|
and old sizes.
|
|
If the new size is larger, the newly allocated memory is
|
|
uninitialized.
|
|
If the requested memory cannot be allocated,
|
|
.Dv NULL
|
|
is returned and the memory referenced by
|
|
.Fa addr
|
|
is unchanged.
|
|
If
|
|
.Fa addr
|
|
is
|
|
.Dv NULL ,
|
|
then
|
|
.Fn realloc
|
|
behaves exactly as
|
|
.Fn malloc .
|
|
If the new size is 0, then
|
|
.Fn realloc
|
|
behaves exactly as
|
|
.Fn free .
|
|
.Pp
|
|
Unlike its standard C library counterpart
|
|
.Pq Xr malloc 3 ,
|
|
the kernel version takes two more arguments.
|
|
.Pp
|
|
The
|
|
.Fa flags
|
|
argument further qualifies
|
|
.Fn malloc
|
|
operational characteristics as follows:
|
|
.Bl -tag -offset indent -width M_NOWAIT
|
|
.It Dv M_NOWAIT
|
|
Causes
|
|
.Fn malloc
|
|
to return
|
|
.Dv NULL
|
|
if the request cannot be immediately fulfilled due to resource shortage.
|
|
If this flag is not set
|
|
(see
|
|
.Dv M_WAITOK ) ,
|
|
.Fn malloc
|
|
will never return
|
|
.Dv NULL .
|
|
.It Dv M_WAITOK
|
|
By default,
|
|
.Fn malloc
|
|
may call
|
|
.Xr cv_wait 9
|
|
to wait for resources to be released by other processes, and this
|
|
flag represents this behaviour.
|
|
Note that
|
|
.Dv M_WAITOK
|
|
is conveniently defined to be 0, and hence may be or'ed into the
|
|
.Fa flags
|
|
argument to indicate that it's ok to wait for resources.
|
|
.It Dv M_ZERO
|
|
Causes the allocated memory to be set to all zeros.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fa type
|
|
argument describes the subsystem and/or use within a subsystem for which
|
|
the allocated memory was needed, and is commonly used to maintain statistics
|
|
about kernel memory usage and, optionally, enforce limits on this usage for
|
|
certain memory types.
|
|
.Pp
|
|
In addition to some built-in generic types defined by the kernel
|
|
memory allocator, subsystems may define their own types.
|
|
.Pp
|
|
The
|
|
.Fn MALLOC_DEFINE
|
|
macro defines a malloc type named
|
|
.Fa type
|
|
with the short description
|
|
.Fa shortdesc ,
|
|
which must be a constant string; this description will be used for
|
|
kernel memory statistics reporting.
|
|
The
|
|
.Fa longdesc
|
|
argument, also a constant string, is intended as way to place a
|
|
comment in the actual type definition, and is not currently stored
|
|
in the type structure.
|
|
If kernel memory statistics are being
|
|
gathered, the system will choose a reasonable default limit for
|
|
the malloc type.
|
|
.Pp
|
|
The
|
|
.Fn MALLOC_DECLARE
|
|
macro is intended for use in header files which are included by
|
|
code which needs to use the malloc type, providing the necessary
|
|
extern declaration.
|
|
.Pp
|
|
Code which includes
|
|
<sys/malloc.h>
|
|
does not need to include
|
|
<sys/mallocvar.h>
|
|
to get these macro definitions.
|
|
The
|
|
<sys/mallocvar.h>
|
|
header file is intended for other header files which need to use the
|
|
.Fn MALLOC_DECLARE
|
|
macro.
|
|
.Pp
|
|
The
|
|
.Fn malloc_type_attach
|
|
function attaches the malloc type
|
|
.Fa type
|
|
to the kernel memory allocator.
|
|
.Pp
|
|
The
|
|
.Fn malloc_type_detach
|
|
function detaches the malloc type
|
|
.Fa type
|
|
previously attached with
|
|
.Fn malloc_type_attach .
|
|
.Pp
|
|
The following generic malloc types are currently defined:
|
|
.Pp
|
|
.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact
|
|
.It Dv M_DEVBUF
|
|
Device driver memory.
|
|
.It Dv M_DMAMAP
|
|
.Xr bus_dma 9
|
|
structures.
|
|
.It Dv M_FREE
|
|
Should be on free list.
|
|
.It Dv M_TEMP
|
|
Misc temporary data buffers.
|
|
.El
|
|
.Pp
|
|
Other malloc types are defined by the corresponding subsystem; see the
|
|
documentation for that subsystem for information about its available malloc
|
|
types.
|
|
.Sh NOTES
|
|
The malloc type argument is actually unused on
|
|
.Nx ,
|
|
the argument is only supported for easier source compatibility
|
|
with
|
|
.Fx
|
|
and
|
|
.Ox .
|
|
Likewise calls to
|
|
.Fn MALLOC_DECLARE ,
|
|
.Fn MALLOC_DEFINE ,
|
|
.Fn malloc_type_attach ,
|
|
and
|
|
.Fn malloc_type_detach
|
|
are defined out and have no effect on
|
|
.Nx .
|
|
.Sh RETURN VALUES
|
|
.Fn malloc
|
|
returns a kernel virtual address that is suitably aligned for storage of
|
|
any type of object.
|
|
.Sh SEE ALSO
|
|
.Xr vmstat 1 ,
|
|
.Xr memoryallocators 9
|