#include <sys/types.h>
#include <sys/malloc.h> void *
malloc (unsigned long size struct malloc_type *type int flags);
MALLOC (space cast unsigned long size struct malloc_type *type int flags); void
free (void *addr struct malloc_type *type);
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
Fa size .
The
free ();
function releases memory at address
Fa addr
that was previously allocated by
malloc ();
for re-use.
The memory is not zeroed.
If
Fa addr
is
NULL
then
free ();
does nothing.
The
realloc ();
function changes the size of the previously allocated memory referenced by
Fa addr
to
Fa 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
Fa addr .
If the requested memory cannot be allocated,
NULL
is returned and the memory referenced by
Fa addr
is valid and unchanged.
If
Fa 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.
The
MALLOC ();
macro variant is functionally equivalent to
Unlike its standard C library counterpart
(malloc(3)
)
the kernel version takes two more arguments.
The
Fa flags
argument further qualifies
malloc (Ns '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 that
M_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
if
M_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.
Exactly one of either
M_WAITOK
or
M_NOWAIT
must be specified.
The
Fa 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
Fa type
is defined using
Vt 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 */
...
MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
In order to use
MALLOC_DEFINE (,);
one must include
#include <sys/param.h>
(instead of
In sys/types.h )
and
In sys/kernel.h .
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 flags
M_NOWAIT
and
M_WAITOK
with the
mbuf(9)
flags
M_DONTWAIT
and
M_TRYWAIT
CONTEXT
malloc (,);
realloc ();
and
reallocf ();
may not be called from fast interrupts handlers.
When called from threaded interrupts,
Fa flags
must contain
M_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, or
NULL
if the request could not be satisfied (implying that
M_NOWAIT
was set).
DIAGNOSTICS
A kernel compiled with the
INVARIANTS
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.
