table of contents
other sections
MALLOC(9) | Kernel Developer's Manual | MALLOC(9) |
NAME¶
malloc, free, realloc, reallocf, MALLOC_DEFINE, MALLOC_DECLARE — kernel memory management routinesSYNOPSIS¶
#include <sys/types.h>#include <sys/malloc.h> void *
malloc(unsigned long size, struct malloc_type *type, int flags); void
free(void *addr, struct malloc_type *type); void *
realloc(void *addr, unsigned long size, struct malloc_type *type, int flags); void *
reallocf(void *addr, unsigned long size, struct malloc_type *type, int flags); MALLOC_DECLARE(type); #include <sys/param.h>
#include <sys/malloc.h>
#include <sys/kernel.h> MALLOC_DEFINE(type, shortdesc, longdesc);
DESCRIPTION¶
The malloc() function allocates uninitialized memory in kernel address space for an object whose size is specified by size. The free() function releases memory at address addr that was previously allocated by malloc() for re-use. The memory is not zeroed. If addr isNULL
, then
free() does nothing.
The realloc() function changes the size of the previously
allocated memory referenced by addr to
size bytes. The contents of the memory are unchanged up
to the lesser of the new and old sizes. Note that the returned value may
differ from addr. If the requested memory cannot be
allocated, NULL
is returned and the memory referenced
by addr is valid and unchanged. If
addr is NULL
, the
realloc() function behaves identically to
malloc() for the specified size.
The reallocf() function is identical to
realloc() except that it will free the passed pointer when
the requested memory cannot be allocated.
Unlike its standard C library counterpart (malloc(3)), the
kernel version takes two more arguments. The flags
argument further qualifies malloc()'s operational
characteristics as follows:
M_ZERO
- Causes the allocated memory to be set to all zeros.
M_NOWAIT
- Causes malloc(),
realloc(), and reallocf() to return
NULL
if the request cannot be immediately fulfilled due to resource shortage. Note thatM_NOWAIT
is required when running in an interrupt context. M_WAITOK
- Indicates that it is OK to wait for resources. If the
request cannot be immediately fulfilled, the current process is put to
sleep to wait for resources to be released by other processes. The
malloc(), realloc(), and
reallocf() functions cannot return
NULL
ifM_WAITOK
is specified. M_USE_RESERVE
- Indicates that the system can dig into its reserve in order
to obtain the requested memory. This option used to be called
M_KERNEL
but has been renamed to something more obvious. This option has been deprecated and is slowly being removed from the kernel, and so should not be used with any new programming.
M_WAITOK
or
M_NOWAIT
must be specified.
The type argument is used to perform statistics on memory
usage, and for basic sanity checks. It can be used to identify multiple
allocations. The statistics can be examined by ‘vmstat -m’.
A type is defined using struct
malloc_type via the MALLOC_DECLARE() and
MALLOC_DEFINE() macros.
/* sys/something/foo_extern.h */ MALLOC_DECLARE(M_FOOBUF); /* sys/something/foo_main.c */ MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); /* sys/something/foo_subr.c */ ... buf = malloc(sizeof *buf, M_FOOBUF, M_NOWAIT);
IMPLEMENTATION NOTES¶
The memory allocator allocates memory in chunks that have size a power of two for requests up to the size of a page of memory. For larger requests, one or more pages is allocated. While it should not be relied upon, this information may be useful for optimizing the efficiency of memory use. Programmers should be careful not to confuse the malloc flagsM_NOWAIT
and M_WAITOK
with the
mbuf(9) flags M_DONTWAIT
and
M_WAIT
.
CONTEXT¶
malloc(), realloc() and reallocf() may not be called from fast interrupts handlers. When called from threaded interrupts, flags must containM_NOWAIT
.
malloc(), realloc() and
reallocf() may sleep when called with
M_WAITOK
. free() never sleeps.
Any calls to malloc() (even with
M_NOWAIT
) or free() when holding a
vnode(9) interlock, will cause a LOR (Lock Order Reversal)
due to the intertwining of VM Objects and Vnodes.
RETURN VALUES¶
The malloc(), realloc(), and reallocf() functions return a kernel virtual address that is suitably aligned for storage of any type of object, orNULL
if the request could not be satisfied (implying
that M_NOWAIT
was set).
DIAGNOSTICS¶
A kernel compiled with theINVARIANTS
configuration
option attempts to detect memory corruption caused by such things as writing
outside the allocated area and imbalanced calls to the
malloc() and free() functions. Failing
consistency checks will cause a panic or a system console message.
SEE ALSO¶
vmstat(8), contigmalloc(9), memguard(9), vnode(9)October 23, 2008 | Debian |