NAME
malloc
, free
— kernel memory
allocator
SYNOPSIS
#include
<sys/types.h>
#include <sys/malloc.h>
void *
malloc
(unsigned
long size, int
type, int
flags);
void
free
(void
*addr, int
type);
DESCRIPTION
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.
The flags argument further qualifies malloc's operational characteristics as follows:
M_WAITOK
- The same as having no other flags specified. If
memory is currently unavailable,
malloc
() may call sleep to wait for resources to be released by other processes. M_NOWAIT
- Causes
malloc
() to returnNULL
if the request cannot be immediately fulfilled due to resource shortage. One ofM_NOWAIT
orM_WAITOK
must be specified. M_CANFAIL
- In the
M_WAITOK
case, if not enough memory is available, returnNULL
instead of calling panic(9).M_CANFAIL
has no effect ifM_NOWAIT
is specified. M_ZERO
- Causes
malloc
() to return zeroed memory.
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_FREE
- Should be on free list.
M_DEVBUF
- Device driver memory.
M_DEBUG
malloc
debug structures.M_PCB
- Protocol control blocks.
M_RTABLE
- Routing tables.
M_FTABLE
- Fragment reassembly headers.
M_IFADDR
- Interface addresses.
M_SOOPTS
- Socket options.
M_SYSCTL
- Sysctl persistent buffers.
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_VNODE
- Dynamically allocated vnodes.
M_CACHE
- Dynamically allocated cache entries.
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_FILE
- Open file structures.
M_FILEDESC
- Open file descriptor tables.
M_PROC
- Proc structures.
M_SUBPROC
- Proc sub-structures.
M_VCLUSTER
- Cluster for VFS.
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_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_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_MEMDESC
- Memory range.
M_CRYPTO_DATA
- crypto(4) data buffers.
M_CREDENTIALS
- ipsec(4) related credentials.
M_PACKET_TAGS
- Packet-attached information tags.
M_EMULDATA
- Per process emulation data.
M_IP6OPT
- IPv6 options.
M_IP6NDP
- IPv6 neighbour discovery structures.
M_TEMP
- Miscellaneous temporary data buffers.
M_NTFSMNT
- NTFS mount structures.
M_NTFSNTNODE
- NTFS ntnode information.
M_NTFSNODE
- NTFS fnode information.
M_NTFSDIR
- NTFS directory buffers.
M_NTFSHASH
- NTFS ntnode hash tables.
M_NTFSVATTR
- 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_BLUETOOTH
- Bluetooth data structures.
M_BWMETER
- Multicast upcall bandwidth meters.
M_UDFMOUNT
- UDF mount structures.
M_UDFFENTRY
- UDF file entries.
M_UDFFID
- UDF file ID.
M_BTHIDEV
- Bluetooth HID.
M_AGP
- AGP memory.
M_DRM
- Direct Rendering Manager.
RETURN VALUES
malloc
() returns 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 the
malloc
() and free
()
functions. 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: “free: unaligned addr”
- panic: “free: duplicated free”
- panic: “free: multiple frees”
- panic: “kmeminit: minbucket too small/struct freelist too big”
- “multiply freed item ⟨addr⟩”
- “Data modified on freelist: ⟨data object description⟩”
DEBUGGING
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
malloc
()
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
free
() with
memory that was returned by the debugging malloc 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.