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

# NAME

`malloc`, `mallocarray`, `free` — kernel memory allocator

# SYNOPSIS

`#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);

# DESCRIPTION

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

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

The `free`() 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 `malloc`() and `mallocarray`() as follows:

`M_WAITOK`
  If memory is currently unavailable, `malloc`() may call sleep to wait for resources to be released by other processes.
`M_NOWAIT`
  Causes `malloc`() to return `NULL` if the request cannot be immediately fulfilled due to resource shortage.
`M_CANFAIL`
  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).
`M_ZERO`
  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:

`M_DEVBUF`
  Device driver memory.
`M_PCB`
  Protocol control blocks.
`M_RTABLE`
  Routing tables.
`M_PF`
  Packet filter structures.
`M_IFADDR`
  Interface addresses.
`M_IFGROUP`
  Interface groups.
`M_SYSCTL`
  Sysctl persistent buffers.
`M_COUNTERS`
  Per-CPU counters via counters_alloc(9).
`M_IOCTLOPS`
  Ioctl data buffers.
`M_IOV`
  Large IOVs.
`M_MOUNT`
  VFS mount structs.
`M_NFSREQ`
  NFS request headers.
`M_NFSMNT`
  NFS mount structures.
`M_LOG`
  Messages in kernel log stash.
`M_VNODE`
  Dynamically allocated vnodes.
`M_DQUOT`
  UFS quota entries.
`M_UFSMNT`
  UFS mount structures.
`M_SHM`
  SVID compatible shared memory segments.
`M_VMMAP`
  VM map structures.
`M_SEM`
  SVID compatible semaphores.
`M_DIRHASH`
  UFS directory hash structures.
`M_ACPI`
  ACPI structures.
`M_VMPMAP`
  VM pmap data.
`M_FILEDESC`
  Open file descriptor tables.
`M_SIGIO`
  Sigio structures.
`M_PROC`
  Proc structures.
`M_SUBPROC`
  Proc sub-structures.
`M_MFSNODE`
  MFS vnode private part.
`M_NETADDR`
  Export host address structures.
`M_NFSSVC`
  NFS server structures.
`M_NFSD`
  NFS server daemon structures.
`M_IPMOPTS`
  Internet multicast options.
`M_IPMADDR`
  Internet multicast addresses.
`M_IFMADDR`
  Link-level multicast addresses.
`M_MRTABLE`
  Multicast routing tables.
`M_ISOFSMNT`
  ISOFS mount structures.
`M_ISOFSNODE`
  ISOFS vnode private part.
`M_MSDOSFSMNT`
  MSDOS FS mount structures.
`M_MSDOSFSFAT`
  MSDOS FS FAT tables.
`M_MSDOSFSNODE`
  MSDOS FS vnode private part.
`M_TTYS`
  Allocated tty structures.
`M_EXEC`
  Argument lists & other mem used by exec.
`M_MISCFSMNT`
  Miscellaneous FS mount structures.
`M_FUSEFS`
  FUSE FS mount structures.
`M_PINSYSCALL`
  pinsyscalls(2) related data.
`M_PFKEY`
  Pfkey data.
`M_TDB`
  Transforms database.
`M_XDATA`
  IPsec data.
`M_PAGEDEP`
  File page dependencies.
`M_INODEDEP`
  Inode dependencies.
`M_NEWBLK`
  New block allocation.
`M_INDIRDEP`
  Indirect block dependencies.
`M_VMSWAP`
  VM swap structures.
`M_UVMAMAP`
  UVM amap and related.
`M_UVMAOBJ`
  UVM aobj and related.
`M_USB`
  USB general.
`M_USBDEV`
  USB device driver.
`M_USBHC`
  USB host controller.
`M_WITNESS`
  witness(4) memory.
`M_MEMDESC`
  Memory range.
`M_CRYPTO_DATA`
  crypto(9) data buffers.
`M_CREDENTIALS`
  ipsec(4) related credentials.
`M_IP6OPT`
  IPv6 options.
`M_IP6NDP`
  IPv6 Neighbor Discovery structures.
`M_TEMP`
  Miscellaneous temporary data buffers.
`M_NTFSMNT`
  NTFS mount structures.
`M_NTFSNTNODE`
  NTFS ntnode information.
`M_NTFSFNODE`
  NTFS fnode information.
`M_NTFSDIR`
  NTFS directory buffers.
`M_NTFSNTHASH`
  NTFS ntnode hash tables.
`M_NTFSNTVATTR`
  NTFS file attribute information.
`M_NTFSRDATA`
  NTFS resident data.
`M_NTFSDECOMP`
  NTFS decompression temporary storage.
`M_NTFSRUN`
  NTFS vrun storage.
`M_KEVENT`
  kqueue(2) data structures.
`M_SYNCACHE`
  SYN cache hash array.
`M_UDFMOUNT`
  UDF mount structures.
`M_UDFFENTRY`
  UDF file entries.
`M_UDFFID`
  UDF file IDs.
`M_AGP`
  AGP memory.
`M_DRM`
  Direct Rendering Manager.

# CONTEXT

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

# RETURN VALUES

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

# DIAGNOSTICS

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:

- panic: “malloc: bogus type”
- panic: “malloc: out of space in kmem_map”
- panic: “malloc: allocation too large”
- panic: “malloc: wrong bucket”
- panic: “malloc: lost data”
- panic: “mallocarray: overflow”
- panic: “free: unaligned addr”
- panic: “free: duplicated free”
- panic: “free: multiple frees”
- panic: “free: non-malloced addr”
- panic: “free: size too large”
- panic: “free: size too small”
- panic: “kmeminit: minbucket too small/struct freelist too big”
- “multiply freed item ⟨addr⟩”
- “Data modified on freelist: ⟨data object description⟩”

# SEE ALSO

systat(1), vmstat(8)

January 19, 2024 | Debian