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