NetBSD/share/man/man9/malloc.9

.\"	$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