MALLOC(9) | Kernel Developer's Manual | MALLOC(9)

# 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.

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)

October 14, 2018 | NetBSD 9.0