These interfaces are being obsoleted and their new use is discouraged. For new code, use
kmem(9) or
pool_cache(9) instead.
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().
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_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.
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
Device driver memory.
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.
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'.