OpenBSD manual page server

Manual Page Search Parameters

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

malloc, mallocarray, freekernel memory allocator

#include <sys/types.h>
#include <sys/malloc.h>

void *
malloc(size_t size, int type, int flags);

void *
mallocarray(size_t nmemb, size_t size, int type, int flags);

void
free(void *addr, int type, size_t size);

The () function allocates uninitialized memory in kernel address space for an object whose size is specified by size.

The () function is the same as malloc(), but allocates space for an array of nmemb objects and checks for arithmetic overflow.

The () function releases memory at address addr that was previously allocated by malloc() or mallocarray() for re-use. The same object size originally provided to malloc() should be specified by size, because free() will operate faster knowing this. If tracking the size is difficult, specify size as 0. If addr is a null pointer, no action occurs.

The flags argument affects the operational characteristics of () and mallocarray() as follows:

If memory is currently unavailable, malloc() may call sleep to wait for resources to be released by other processes.
Causes malloc() to return NULL if the request cannot be immediately fulfilled due to resource shortage.
In the M_WAITOK case, if not enough memory is available, return NULL instead of calling panic(9). If mallocarray() detects an overflow or malloc() detects an excessive allocation, return NULL instead of calling panic(9).
Causes allocated memory to be zeroed.

One of M_NOWAIT or M_WAITOK must be specified via the flags argument.

The type argument broadly identifies the kernel subsystem for which the allocated memory was needed, and is commonly used to maintain statistics about kernel memory usage. These statistics can be examined using vmstat(8) or systat(1) if either of the kernel options(4) KMEMSTATS or DEBUG are enabled.

The following types are currently defined:

Should be on free list.
Device driver memory.
malloc debug structures.
Protocol control blocks.
Routing tables.
Fragment reassembly headers.
Interface addresses.
Socket options.
Sysctl persistent buffers.
Per-CPU Counters for use via counters_alloc(9).
Ioctl data buffers.
Large IOVs.
VFS mount structs.
NFS request headers.
NFS mount structures.
Dynamically allocated vnodes.
Dynamically allocated cache entries.
UFS quota entries.
UFS mount structures.
SVID compatible shared memory segments.
VM map structures.
SVID compatible semaphores.
UFS directory hash structures.
ACPI structures.
VM pmap data.
Open file structures.
Open file descriptor tables.
Proc structures.
Proc sub-structures.
Cluster for VFS.
MFS vnode private part.
Export host address structures.
NFS server structures.
NFS server daemon structures.
Internet multicast options.
Internet multicast addresses.
Link-level multicast addresses.
Multicast routing tables.
ISOFS mount structures.
ISOFS vnode private part.
MSDOS FS mount structures.
MSDOS FS FAT tables.
MSDOS FS vnode private part.
Allocated tty structures.
Argument lists & other mem used by exec.
Miscellaneous FS mount structures.
FUSE FS mount structures.
Pfkey data.
Transforms database.
IPsec data.
File page dependencies.
Inode dependencies.
New block allocation.
Indirect block dependencies.
VM swap structures.
UVM amap and related.
UVM aobj and related.
USB general.
USB device driver.
USB host controller.
Memory range.
crypto(9) data buffers.
ipsec(4) related credentials.
Per process emulation data.
IPv6 options.
IPv6 neighbour discovery structures.
Miscellaneous temporary data buffers.
NTFS mount structures.
NTFS ntnode information.
NTFS fnode information.
NTFS directory buffers.
NTFS ntnode hash tables.
NTFS file attribute information.
NTFS resident data.
NTFS decompression temporary storage.
NTFS vrun storage.
kqueue(2) data structures.
UDF mount structures.
UDF file entries.
UDF file ID.
AGP memory.
Direct Rendering Manager.

malloc() and mallocarray() can be called during autoconf, from process context, or from interrupt context if M_NOWAIT is passed via flags. They can't be called from interrupt context if M_WAITOK is passed via flags.

free() can be called during autoconf, from process context, or from interrupt context.

malloc() and mallocarray() return a kernel virtual address that is suitably aligned for storage of any type of object.

A kernel compiled with the DIAGNOSTIC configuration option attempts to detect memory corruption caused by such things as writing outside the allocated area and unbalanced calls to malloc() or mallocarray(), and free(). Failing consistency checks will cause a panic or a system console message:

A kernel compiled with the MALLOC_DEBUG option allows for more extensive debugging of memory allocations. The debug_malloc_type, debug_malloc_size, debug_malloc_size_lo and debug_malloc_size_hi variables choose which allocation to debug. debug_malloc_type should be set to the memory type and debug_malloc_size should be set to the memory size to debug. 0 can be used as a wildcard. debug_malloc_size_lo and debug_malloc_size_hi can be used to specify a range of sizes if the exact size to debug is not known. When those are used, debug_malloc_size needs to be set to the wildcard. M_DEBUG can also be specified as an allocation type to force allocation with debugging.

Every call to () or mallocarray() with a memory type and size that matches the debugged type and size will allocate two virtual pages. The pointer returned will be aligned so that the requested area will end at the page boundary and the second virtual page will be left unmapped. This way we can catch reads and writes outside the allocated area.

Every call to () with memory that was returned by the debugging allocators will cause the memory area to become unmapped so that we can catch dangling reads and writes to freed memory.

There are no special diagnostics if any errors are caught by the debugging malloc. The errors will look like normal access to unmapped memory. On a memory access error, the show malloc command in ddb(4) can be invoked to see what memory areas are allocated and freed. If the faulting address is within two pages from an address on the allocated list, there was an access outside the allocated area. If the faulting address is within two pages from an address on the free list, there was an access to freed memory.

Care needs to be taken when using the MALLOC_DEBUG option: the memory consumption can run away pretty quickly and there is a severe performance degradation when allocating and freeing debugged memory types.

systat(1), vmstat(8)

November 14, 2016 OpenBSD-6.2