malloc(9)

NAME

malloc, MALLOC, free, FREE, realloc, reallocf,

MALLOC_DEFINE

MALLOC_DECLARE - kernel memory management routines

SYNOPSIS

#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 ker

nel 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 is
NULL, 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 memo

ry cannot be
allocated, NULL is returned and the memory referenced by

addr is valid
and unchanged. If addr is NULL, the realloc() function be

haves 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

(space) = (cast)malloc((u_long)(size), type, flags)

and the FREE() macro variant is equivalent to

free((addr), type)

Unlike its standard C library counterpart (malloc(3)), the

kernel version
takes two more arguments. The flags argument further quali

fies
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 re

source 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 ob

vious. This
option has been deprecated and is slowly being re

moved from the
kernel, and so should not be used with any new pro

gramming.

Exactly one of either M_WAITOK or M_NOWAIT must be speci

fied.

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

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 and

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 ef

ficiency 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_TRY

WAIT.

CONTEXT

malloc(), realloc() and reallocf() may not be called from

fast interrupts
handlers. When called from threaded interrupts, 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.

SEE ALSO

vmstat(8), contigmalloc(9), memguard(9), vnode(9)

BSD June 12, 2003

BSD