NAME
malloc,
realloc,
free,
malloc_type_attach,
malloc_type_detach,
MALLOC_DEFINE,
MALLOC_DECLARE —
general-purpose kernel memory allocator
SYNOPSIS
#include <sys/malloc.h>
void *
malloc(
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);
void
malloc_type_attach(
struct
malloc_type *type);
void
malloc_type_detach(
struct
malloc_type *type);
#include <sys/mallocvar.h>
MALLOC_DEFINE(
type,
shortdesc,
longdesc);
MALLOC_JUSTDEFINE(
type,
shortdesc,
longdesc);
MALLOC_DECLARE(
type);
DESCRIPTION
These interfaces
are being obsoleted and their new use is discouraged. For new code, use
kmem(9) for variable-sized or
one-time allocations and
pool_cache(9) for frequent
fixed-size allocations instead.
The
malloc() function allocates uninitialized memory in kernel
address space for an object whose size is specified by
size.
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().
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
- Causes malloc() 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
- By default, malloc() 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
- Causes the allocated memory to be set to all zeros.
-
-
M_CANFAIL
- Changes behaviour for
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() 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. 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.
The
malloc_type_detach() function detaches the malloc type
type previously attached with
malloc_type_attach().
The following generic malloc types are currently defined:
M_DEVBUF
- Device driver memory.
M_DMAMAP
- bus_dma(9)
structures.
M_FREE
- Should be on free list.
M_PCB
- Protocol control block.
M_SOFTINTR
- Softinterrupt structures.
M_TEMP
- Misc temporary data buffers.
Other malloc types are defined by the corresponding subsystem; see the
documentation for that subsystem for information its available malloc types.
RETURN VALUES
malloc() returns a kernel virtual address that is suitably
aligned for storage of any type of object.
SEE ALSO
vmstat(1),
memoryallocators(9)