void
*
malloc(
unsigned long size
, struct malloc_type *type
, int flags
)
MALLOC(
space
, cast
, unsigned long size
, struct malloc_type *type
, int flags
)
void
*
realloc(
void *addr
, unsigned long newsize
, struct malloc_type *type
, int flags
)
void
free(
void *addr
, struct malloc_type *type
)
FREE(
void *addr
, struct malloc_type *type
)
unsigned
long
malloc_roundup(
unsigned long size
)
void
malloc_type_attach(
struct malloc_type *type
)
void
malloc_type_detach(
struct malloc_type *type
)
void
malloc_type_setlimit(
struct malloc_type *type
, unsigned long limit
)
MALLOC_DEFINE_LIMIT(
type
, shortdesc
, longdesc
, limit
)
MALLOC_JUSTDEFINE_LIMIT(
type
, shortdesc
, longdesc
, limit
)
MALLOC_DEFINE(
type
, shortdesc
, longdesc
)
MALLOC_JUSTDEFINE(
type
, shortdesc
, longdesc
)
MALLOC_DECLARE(
type
)
The
malloc()
function allocates uninitialized memory in kernel address space for an
object whose size is specified by
size
.
malloc_roundup()
returns the actual size of the allocation unit for the given value.
free(
)
releases memory at address
addr
that was previously allocated by
malloc()
for re-use.
Unlike
free(3),
free(
)
does not accept an
addr
argument that is
NULL
.
The
realloc()
function changes the size of the previously allocated memory referenced
by
addr
to
size
and returns a pointer to the
(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,
NULL
is returned and the memory referenced by
addr
is unchanged.
If
addr
is
NULL
,
then
realloc()
behaves exactly as
malloc(
).
If the new size is 0, then
realloc(
)
behaves exactly as
free(
).
The
MALLOC()
macro variant is functionally equivalent to
(space) = (cast)malloc((u_long)(size), type, flags)
and the
FREE()
macro variant is equivalent to
free((void *)(addr), type)
The
MALLOC()
macro is intended to be used with a compile-time constant
size
so that the compiler can do constant folding.
In the comparison to
malloc()
and
free(
)
functions, the
MALLOC(
)
and
FREE(
)
macros may be faster, at the cost of increased code size.
There is no difference between the memory allocated with MALLOC and malloc.
i.e., no matter which MALLOC or malloc is used to allocate the memory,
either FREE or free can be used to free it.
Unlike its standard C library counterpart (malloc(3)), the kernel version takes two more arguments.
The
flags
argument further qualifies
malloc()
operational characteristics as follows:
M_NOWAIT
)
to return
NULL
if the request cannot be immediately fulfilled due to resource shortage.
If this flag is not set
(see
M_WAITOK
),
malloc(
)
will never return
NULL
.
M_WAITOK
)
may call
cv_wait(9)
to wait for resources to be released by other processes, and this
flag represents this behaviour.
Note that
M_WAITOK
is conveniently defined to be 0, and hence may be or'ed into the
flags
argument to indicate that it's ok to wait for resources.
M_ZERO
M_CANFAIL
M_WAITOK
case - if the requested memory size is bigger than
malloc(
)
can ever allocate, return failure, rather than calling
panic(9).
This is different to M_NOWAIT, since
the call can still wait for resources.
Rather than depending on
M_CANFAIL
,
kernel code should do proper bound checking itself.
This flag should only be used in cases where this is not feasible.
Since it can hide real kernel bugs, its usage is
strongly discouraged.
The
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.
In addition to some built-in generic types defined by the kernel memory allocator, subsystems may define their own types.
The
MALLOC_DEFINE_LIMIT()
macro defines a malloc type named
type
with the short description
shortdesc
,
which must be a constant string; this description will be used for
kernel memory statistics reporting.
The
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.
The
limit
argument specifies the maximum amount of memory, in bytes, that this
malloc type can consume.
The
MALLOC_DEFINE()
macro is equivalent to the
MALLOC_DEFINE_LIMIT(
)
macro with a
limit
argument of 0.
If kernel memory statistics are being gathered, the system will
choose a reasonable default limit for the malloc type.
The
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.
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
MALLOC_DECLARE()
macro.
The
malloc_type_attach()
function attaches the malloc type
type
to the kernel memory allocator.
This is intended for use by LKMs; malloc types included in modules
statically-linked into the kernel are automatically registered with
the kernel memory allocator.
However, it is possible to define malloc types without automatically
registering them using
MALLOC_JUSTDEFINE()
or
MALLOC_JUSTDEFINE_LIMIT(
).
Apart from not automatically registering to the kernel a boot time,
these functions are equivalent to their counterparts.
They can be used when a separate LKM codepath for initialization is
not desired.
The
malloc_type_detach()
function detaches the malloc type
type
previously attached with
malloc_type_attach().
The
malloc_type_setlimit()
function sets the memory limit of the malloc type
type
to
limit
bytes.
The type must already be registered with the kernel memory allocator.
The following generic malloc types are currently defined:
M_DEVBUF
M_DMAMAP
M_FREE
M_PCB
M_SOFTINTR
M_TEMP
Other malloc types are defined by the corresponding subsystem; see the documentation for that subsystem for information its available malloc types.
Statistics based on the
type
argument are maintained only if the kernel option
KMEMSTATS
is used when compiling the kernel
(the default in current NetBSD kernels)
and can be examined by using
`vmstat -m'.
)
returns a kernel virtual address that is suitably aligned for storage of
any type of object.
DIAGNOSTIC
configuration option attempts to detect memory corruption caused by
such things as writing outside the allocated area and imbalanced calls to the
malloc(
)
and
free(
)
functions.
Failing consistency checks will cause a panic or a system console message: