1997-03-22 23:50:21 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
1999-09-29 16:49:18 +00:00
|
|
|
.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
|
1999-08-28 00:22:10 +00:00
|
|
|
.\" $FreeBSD$
|
1999-07-12 21:02:10 +00:00
|
|
|
.\"
|
2021-03-06 10:25:12 +00:00
|
|
|
.Dd March 6, 2021
|
1997-03-22 23:50:21 +00:00
|
|
|
.Dt MALLOC 9
|
2001-07-10 15:31:11 +00:00
|
|
|
.Os
|
1997-03-22 23:50:21 +00:00
|
|
|
.Sh NAME
|
|
|
|
.Nm malloc ,
|
|
|
|
.Nm free ,
|
2003-04-09 08:27:32 +00:00
|
|
|
.Nm realloc ,
|
|
|
|
.Nm reallocf ,
|
|
|
|
.Nm MALLOC_DEFINE ,
|
|
|
|
.Nm MALLOC_DECLARE
|
1997-03-22 23:50:21 +00:00
|
|
|
.Nd kernel memory management routines
|
|
|
|
.Sh SYNOPSIS
|
2001-10-01 16:09:29 +00:00
|
|
|
.In sys/types.h
|
|
|
|
.In sys/malloc.h
|
1997-03-22 23:50:21 +00:00
|
|
|
.Ft void *
|
2018-01-24 19:37:18 +00:00
|
|
|
.Fn malloc "size_t size" "struct malloc_type *type" "int flags"
|
2018-01-07 13:21:01 +00:00
|
|
|
.Ft void *
|
|
|
|
.Fn mallocarray "size_t nmemb" "size_t size" "struct malloc_type *type" "int flags"
|
1997-03-22 23:50:21 +00:00
|
|
|
.Ft void
|
1997-10-11 08:11:31 +00:00
|
|
|
.Fn free "void *addr" "struct malloc_type *type"
|
2020-02-16 00:12:53 +00:00
|
|
|
.Ft void
|
|
|
|
.Fn zfree "void *addr" "struct malloc_type *type"
|
2002-03-13 01:42:33 +00:00
|
|
|
.Ft void *
|
2018-01-24 19:37:18 +00:00
|
|
|
.Fn realloc "void *addr" "size_t size" "struct malloc_type *type" "int flags"
|
2002-03-13 01:42:33 +00:00
|
|
|
.Ft void *
|
2018-01-24 19:37:18 +00:00
|
|
|
.Fn reallocf "void *addr" "size_t size" "struct malloc_type *type" "int flags"
|
2020-08-29 19:26:31 +00:00
|
|
|
.Ft size_t
|
|
|
|
.Fn malloc_usable_size "const void *addr"
|
2020-11-02 17:38:08 +00:00
|
|
|
.Ft void *
|
|
|
|
.Fn malloc_exec "size_t size" "struct malloc_type *type" "int flags"
|
2003-05-21 15:49:01 +00:00
|
|
|
.Fn MALLOC_DECLARE type
|
2003-04-09 08:27:32 +00:00
|
|
|
.In sys/param.h
|
|
|
|
.In sys/malloc.h
|
|
|
|
.In sys/kernel.h
|
2003-05-21 15:49:01 +00:00
|
|
|
.Fn MALLOC_DEFINE type shortdesc longdesc
|
2018-10-30 18:26:34 +00:00
|
|
|
.In sys/param.h
|
|
|
|
.In sys/domainset.h
|
|
|
|
.Ft void *
|
|
|
|
.Fn malloc_domainset "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
|
2020-11-02 17:38:08 +00:00
|
|
|
.Ft void *
|
|
|
|
.Fn malloc_domainset_exec "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
|
2021-03-06 10:25:12 +00:00
|
|
|
.Ft void *
|
|
|
|
.Fn mallocarray_domainset "size_t nmemb" "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
|
1997-03-22 23:50:21 +00:00
|
|
|
.Sh DESCRIPTION
|
|
|
|
The
|
|
|
|
.Fn malloc
|
|
|
|
function allocates uninitialized memory in kernel address space for an
|
|
|
|
object whose size is specified by
|
|
|
|
.Fa size .
|
2002-03-13 01:42:33 +00:00
|
|
|
.Pp
|
2003-02-05 14:00:46 +00:00
|
|
|
The
|
2018-10-30 18:26:34 +00:00
|
|
|
.Fn malloc_domainset
|
|
|
|
variant allocates memory from a specific
|
|
|
|
.Xr numa 4
|
|
|
|
domain using the specified domain selection policy.
|
2018-03-24 23:58:44 +00:00
|
|
|
See
|
2018-10-30 18:26:34 +00:00
|
|
|
.Xr domainset 9
|
|
|
|
for some example policies.
|
2018-03-24 23:58:44 +00:00
|
|
|
.Pp
|
2020-11-02 17:38:08 +00:00
|
|
|
Both
|
|
|
|
.Fn malloc_exec
|
|
|
|
and
|
|
|
|
.Fn malloc_domainset_exec
|
|
|
|
can be used to return executable memory.
|
|
|
|
Not all platforms enforce a distinction between executable and non-executable memory.
|
|
|
|
.Pp
|
2018-03-24 23:58:44 +00:00
|
|
|
The
|
2018-01-07 13:21:01 +00:00
|
|
|
.Fn mallocarray
|
|
|
|
function allocates uninitialized memory in kernel address space for an
|
|
|
|
array of
|
|
|
|
.Fa nmemb
|
|
|
|
entries whose size is specified by
|
|
|
|
.Fa size .
|
|
|
|
.Pp
|
|
|
|
The
|
2021-03-06 10:25:12 +00:00
|
|
|
.Fn mallocarray_domainset
|
|
|
|
variant allocates memory from a specific
|
|
|
|
.Xr numa 4
|
|
|
|
domain using the specified domain selection policy.
|
|
|
|
See
|
|
|
|
.Xr domainset 9
|
|
|
|
for some example policies.
|
|
|
|
.Pp
|
|
|
|
The
|
1997-03-22 23:50:21 +00:00
|
|
|
.Fn free
|
2003-02-05 14:00:46 +00:00
|
|
|
function releases memory at address
|
1997-03-22 23:50:21 +00:00
|
|
|
.Fa addr
|
|
|
|
that was previously allocated by
|
|
|
|
.Fn malloc
|
2002-03-13 01:42:33 +00:00
|
|
|
for re-use.
|
|
|
|
The memory is not zeroed.
|
|
|
|
If
|
|
|
|
.Fa addr
|
|
|
|
is
|
|
|
|
.Dv NULL ,
|
|
|
|
then
|
|
|
|
.Fn free
|
|
|
|
does nothing.
|
|
|
|
.Pp
|
2020-02-16 00:12:53 +00:00
|
|
|
Like
|
|
|
|
.Fn free ,
|
|
|
|
the
|
|
|
|
.Fn zfree
|
|
|
|
function releases memory at address
|
|
|
|
.Fa addr
|
|
|
|
that was previously allocated by
|
|
|
|
.Fn malloc
|
|
|
|
for re-use.
|
|
|
|
However,
|
|
|
|
.Fn zfree
|
|
|
|
will zero the memory before it is released.
|
|
|
|
.Pp
|
2002-03-13 01:42:33 +00:00
|
|
|
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
|
2002-03-18 10:52:09 +00:00
|
|
|
function is identical to
|
|
|
|
.Fn realloc
|
|
|
|
except that it
|
2002-03-13 01:42:33 +00:00
|
|
|
will free the passed pointer when the requested memory cannot be allocated.
|
|
|
|
.Pp
|
2020-08-29 19:26:31 +00:00
|
|
|
The
|
|
|
|
.Fn malloc_usable_size
|
|
|
|
function returns the usable size of the allocation pointed to by
|
|
|
|
.Fa addr .
|
|
|
|
The return value may be larger than the size that was requested during
|
|
|
|
allocation.
|
|
|
|
.Pp
|
1997-03-22 23:50:21 +00:00
|
|
|
Unlike its standard C library counterpart
|
|
|
|
.Pq Xr malloc 3 ,
|
2003-05-21 15:49:01 +00:00
|
|
|
the kernel version takes two more arguments.
|
|
|
|
The
|
1997-03-22 23:50:21 +00:00
|
|
|
.Fa flags
|
|
|
|
argument further qualifies
|
2001-02-07 10:11:57 +00:00
|
|
|
.Fn malloc Ns 's
|
1997-03-22 23:50:21 +00:00
|
|
|
operational characteristics as follows:
|
1998-12-23 01:05:06 +00:00
|
|
|
.Bl -tag -width indent
|
2000-10-20 17:54:55 +00:00
|
|
|
.It Dv M_ZERO
|
|
|
|
Causes the allocated memory to be set to all zeros.
|
2012-01-28 17:21:12 +00:00
|
|
|
.It Dv M_NODUMP
|
2012-03-29 05:02:12 +00:00
|
|
|
For allocations greater than page size, causes the allocated
|
2012-01-28 17:21:12 +00:00
|
|
|
memory to be excluded from kernel core dumps.
|
1997-03-22 23:50:21 +00:00
|
|
|
.It Dv M_NOWAIT
|
|
|
|
Causes
|
2002-03-13 01:42:33 +00:00
|
|
|
.Fn malloc ,
|
|
|
|
.Fn realloc ,
|
2002-03-18 10:52:09 +00:00
|
|
|
and
|
2002-03-13 01:42:33 +00:00
|
|
|
.Fn reallocf
|
1997-03-22 23:50:21 +00:00
|
|
|
to return
|
|
|
|
.Dv NULL
|
|
|
|
if the request cannot be immediately fulfilled due to resource shortage.
|
2002-03-13 01:42:33 +00:00
|
|
|
Note that
|
|
|
|
.Dv M_NOWAIT
|
|
|
|
is required when running in an interrupt context.
|
2003-02-24 05:53:27 +00:00
|
|
|
.It Dv M_WAITOK
|
2003-05-21 15:49:01 +00:00
|
|
|
Indicates that it is OK to wait for resources.
|
|
|
|
If the request cannot be immediately fulfilled, the current process is put
|
2003-04-09 08:27:32 +00:00
|
|
|
to sleep to wait for resources to be released by other processes.
|
2004-02-16 21:36:59 +00:00
|
|
|
The
|
2002-03-13 01:42:33 +00:00
|
|
|
.Fn malloc ,
|
2018-01-10 21:49:45 +00:00
|
|
|
.Fn mallocarray ,
|
2002-03-13 01:42:33 +00:00
|
|
|
.Fn realloc ,
|
|
|
|
and
|
|
|
|
.Fn reallocf
|
2004-02-16 21:36:59 +00:00
|
|
|
functions cannot return
|
1998-12-23 01:05:06 +00:00
|
|
|
.Dv NULL
|
2004-02-16 21:36:59 +00:00
|
|
|
if
|
|
|
|
.Dv M_WAITOK
|
|
|
|
is specified.
|
2018-01-10 22:20:49 +00:00
|
|
|
If the multiplication of
|
2018-01-07 13:21:01 +00:00
|
|
|
.Fa nmemb
|
|
|
|
and
|
|
|
|
.Fa size
|
2018-01-10 21:49:45 +00:00
|
|
|
would cause an integer overflow, the
|
|
|
|
.Fn mallocarray
|
|
|
|
function induces a panic.
|
1999-09-29 16:49:18 +00:00
|
|
|
.It Dv M_USE_RESERVE
|
2012-11-16 06:40:40 +00:00
|
|
|
Indicates that the system can use its reserve of memory to satisfy the
|
|
|
|
request.
|
2012-11-16 11:56:53 +00:00
|
|
|
This option should only be used in combination with
|
2012-11-16 06:40:40 +00:00
|
|
|
.Dv M_NOWAIT
|
|
|
|
when an allocation failure cannot be tolerated by the caller without
|
|
|
|
catastrophic effects on the system.
|
1997-03-22 23:50:21 +00:00
|
|
|
.El
|
|
|
|
.Pp
|
2003-04-09 08:27:32 +00:00
|
|
|
Exactly one of either
|
|
|
|
.Dv M_WAITOK
|
|
|
|
or
|
|
|
|
.Dv M_NOWAIT
|
|
|
|
must be specified.
|
|
|
|
.Pp
|
1997-03-22 23:50:21 +00:00
|
|
|
The
|
|
|
|
.Fa type
|
1997-10-11 08:11:31 +00:00
|
|
|
argument is used to perform statistics on memory usage, and for
|
|
|
|
basic sanity checks.
|
2003-05-06 19:10:17 +00:00
|
|
|
It can be used to identify multiple allocations.
|
1997-10-11 08:11:31 +00:00
|
|
|
The statistics can be examined by
|
|
|
|
.Sq vmstat -m .
|
1997-03-22 23:50:21 +00:00
|
|
|
.Pp
|
1997-10-11 08:11:31 +00:00
|
|
|
A
|
1997-03-22 23:50:21 +00:00
|
|
|
.Fa type
|
2003-04-09 08:27:32 +00:00
|
|
|
is defined using
|
2003-05-21 15:49:01 +00:00
|
|
|
.Vt "struct malloc_type"
|
2003-04-09 08:27:32 +00:00
|
|
|
via the
|
1999-09-29 16:49:18 +00:00
|
|
|
.Fn MALLOC_DECLARE
|
|
|
|
and
|
|
|
|
.Fn MALLOC_DEFINE
|
|
|
|
macros.
|
1997-10-11 08:11:31 +00:00
|
|
|
.Bd -literal -offset indent
|
|
|
|
/* sys/something/foo_extern.h */
|
|
|
|
|
1999-09-29 16:49:18 +00:00
|
|
|
MALLOC_DECLARE(M_FOOBUF);
|
1997-10-11 08:11:31 +00:00
|
|
|
|
|
|
|
/* sys/something/foo_main.c */
|
|
|
|
|
1999-09-29 16:49:18 +00:00
|
|
|
MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
|
1997-10-11 08:11:31 +00:00
|
|
|
|
|
|
|
/* sys/something/foo_subr.c */
|
|
|
|
|
2000-12-29 09:18:45 +00:00
|
|
|
\&...
|
2012-07-17 02:05:39 +00:00
|
|
|
buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT);
|
1997-10-11 08:11:31 +00:00
|
|
|
|
1998-12-23 01:05:06 +00:00
|
|
|
.Ed
|
2003-04-09 08:27:32 +00:00
|
|
|
.Pp
|
|
|
|
In order to use
|
2003-05-21 15:49:01 +00:00
|
|
|
.Fn MALLOC_DEFINE ,
|
2003-04-09 08:27:32 +00:00
|
|
|
one must include
|
2003-09-08 19:57:22 +00:00
|
|
|
.In sys/param.h
|
2003-04-09 08:27:32 +00:00
|
|
|
(instead of
|
2003-09-08 19:57:22 +00:00
|
|
|
.In sys/types.h )
|
2003-04-09 08:27:32 +00:00
|
|
|
and
|
2003-09-08 19:57:22 +00:00
|
|
|
.In sys/kernel.h .
|
2003-06-12 09:03:15 +00:00
|
|
|
.Sh CONTEXT
|
2003-04-09 08:27:32 +00:00
|
|
|
.Fn malloc ,
|
|
|
|
.Fn realloc
|
|
|
|
and
|
|
|
|
.Fn reallocf
|
|
|
|
may not be called from fast interrupts handlers.
|
2003-05-21 15:49:01 +00:00
|
|
|
When called from threaded interrupts,
|
|
|
|
.Fa flags
|
2003-04-09 08:27:32 +00:00
|
|
|
must contain
|
|
|
|
.Dv M_NOWAIT .
|
|
|
|
.Pp
|
|
|
|
.Fn malloc ,
|
|
|
|
.Fn realloc
|
|
|
|
and
|
|
|
|
.Fn reallocf
|
2003-06-12 09:03:15 +00:00
|
|
|
may sleep when called with
|
|
|
|
.Dv M_WAITOK .
|
2003-04-09 08:27:32 +00:00
|
|
|
.Fn free
|
2003-06-12 09:03:15 +00:00
|
|
|
never sleeps.
|
2015-11-19 14:04:53 +00:00
|
|
|
However,
|
|
|
|
.Fn malloc ,
|
2016-01-08 13:33:22 +00:00
|
|
|
.Fn realloc ,
|
2015-11-19 14:04:53 +00:00
|
|
|
.Fn reallocf
|
|
|
|
and
|
|
|
|
.Fn free
|
|
|
|
may not be called in a critical section or while holding a spin lock.
|
2003-01-18 19:51:52 +00:00
|
|
|
.Pp
|
|
|
|
Any calls to
|
|
|
|
.Fn malloc
|
2003-04-09 08:27:32 +00:00
|
|
|
(even with
|
|
|
|
.Dv M_NOWAIT )
|
2003-01-18 19:51:52 +00:00
|
|
|
or
|
|
|
|
.Fn free
|
|
|
|
when holding a
|
|
|
|
.Xr vnode 9
|
|
|
|
interlock, will cause a LOR (Lock Order Reversal) due to the
|
2004-06-21 14:11:45 +00:00
|
|
|
intertwining of VM Objects and Vnodes.
|
2014-11-23 21:00:00 +00:00
|
|
|
.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.
|
2005-01-21 08:36:40 +00:00
|
|
|
.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).
|
1997-03-22 23:50:21 +00:00
|
|
|
.Sh DIAGNOSTICS
|
|
|
|
A kernel compiled with the
|
2003-04-09 08:27:32 +00:00
|
|
|
.Dv INVARIANTS
|
1999-02-12 02:12:08 +00:00
|
|
|
configuration option attempts to detect memory corruption caused by
|
1997-03-22 23:50:21 +00:00
|
|
|
such things as writing outside the allocated area and imbalanced calls to the
|
|
|
|
.Fn malloc
|
|
|
|
and
|
|
|
|
.Fn free
|
2000-03-03 14:05:08 +00:00
|
|
|
functions.
|
|
|
|
Failing consistency checks will cause a panic or a system console
|
2003-04-09 08:27:32 +00:00
|
|
|
message.
|
2005-01-21 08:36:40 +00:00
|
|
|
.Sh SEE ALSO
|
2018-10-30 18:26:34 +00:00
|
|
|
.Xr numa 4 ,
|
2005-01-21 08:36:40 +00:00
|
|
|
.Xr vmstat 8 ,
|
|
|
|
.Xr contigmalloc 9 ,
|
2018-10-30 18:26:34 +00:00
|
|
|
.Xr domainset 9 ,
|
2005-02-22 17:20:20 +00:00
|
|
|
.Xr memguard 9 ,
|
2005-01-21 08:36:40 +00:00
|
|
|
.Xr vnode 9
|