free(9)
- NetBSD Manual Pages
MALLOC(9) NetBSD Kernel Developer's Manual MALLOC(9)
NAME
malloc, realloc, free, malloc_type_attach, malloc_type_detach,
MALLOC_DEFINE, MALLOC_DECLARE -- general-purpose kernel memory allocator
SYNOPSIS
#include <sys/malloc.h>
void *
malloc(unsigned long size, struct malloc_type *type, int flags);
void *
realloc(void *addr, unsigned long newsize, struct malloc_type *type,
int flags);
void
free(void *addr, struct malloc_type *type);
void
malloc_type_attach(struct malloc_type *type);
void
malloc_type_detach(struct malloc_type *type);
#include <sys/mallocvar.h>
MALLOC_DEFINE(type, shortdesc, longdesc);
MALLOC_JUSTDEFINE(type, shortdesc, longdesc);
MALLOC_DECLARE(type);
DESCRIPTION
These interfaces are being obsoleted and their new use is discouraged.
For new code, use kmem(9) for variable-sized or one-time allocations and
pool_cache(9) for frequent fixed-size allocations instead.
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. Unlike free(3), free() does not accept an addr argument that is
NULL.
The realloc() function changes the size of the previously allocated mem-
ory referenced by addr to size and returns a pointer to the (possibly
moved) object. The memory contents are unchanged up to the lesser of the
new and old sizes. If the new size is larger, the newly allocated memory
is uninitialized. If the requested memory cannot be allocated, NULL is
returned and the memory referenced by addr is unchanged. If addr is
NULL, then realloc() behaves exactly as malloc(). If the new size is 0,
then realloc() behaves exactly as free().
Unlike its standard C library counterpart (malloc(3)), the kernel version
takes two more arguments.
The flags argument further qualifies malloc() operational characteristics
as follows:
M_NOWAIT Causes malloc() to return NULL if the request cannot be
immediately fulfilled due to resource shortage. If this
flag is not set (see M_WAITOK), malloc() will never
return NULL.
M_WAITOK By default, malloc() may call cv_wait(9) to wait for
resources to be released by other processes, and this
flag represents this behaviour. Note that M_WAITOK is
conveniently defined to be 0, and hence may be or'ed
into the flags argument to indicate that it's ok to wait
for resources.
M_ZERO Causes the allocated memory to be set to all zeros.
M_CANFAIL Changes behaviour for M_WAITOK case - if the requested
memory size is bigger than malloc() can ever allocate,
return failure, rather than calling panic(9). This is
different to M_NOWAIT, since the call can still wait for
resources.
Rather than depending on M_CANFAIL, kernel code should
do proper bound checking itself. This flag should only
be used in cases where this is not feasible. Since it
can hide real kernel bugs, its usage is strongly
discouraged.
The type argument describes the subsystem and/or use within a subsystem
for which the allocated memory was needed, and is commonly used to main-
tain statistics about kernel memory usage and, optionally, enforce limits
on this usage for certain memory types.
In addition to some built-in generic types defined by the kernel memory
allocator, subsystems may define their own types.
The MALLOC_DEFINE() macro defines a malloc type named type with the short
description shortdesc, which must be a constant string; this description
will be used for kernel memory statistics reporting. The longdesc argu-
ment, also a constant string, is intended as way to place a comment in
the actual type definition, and is not currently stored in the type
structure. If kernel memory statistics are being gathered, the system
will choose a reasonable default limit for the malloc type.
The MALLOC_DECLARE() macro is intended for use in header files which are
included by code which needs to use the malloc type, providing the neces-
sary extern declaration.
Code which includes <sys/malloc.h> does not need to include <sys/malloc-
var.h> to get these macro definitions. The <sys/mallocvar.h> header file
is intended for other header files which need to use the MALLOC_DECLARE()
macro.
The malloc_type_attach() function attaches the malloc type type to the
kernel memory allocator.
The malloc_type_detach() function detaches the malloc type type previ-
ously attached with malloc_type_attach().
The following generic malloc types are currently defined:
M_DEVBUF Device driver memory.
M_DMAMAP bus_dma(9) structures.
M_FREE Should be on free list.
M_PCB Protocol control block.
M_SOFTINTR Softinterrupt structures.
M_TEMP Misc temporary data buffers.
Other malloc types are defined by the corresponding subsystem; see the
documentation for that subsystem for information its available malloc
types.
RETURN VALUES
malloc() returns a kernel virtual address that is suitably aligned for
storage of any type of object.
SEE ALSO
vmstat(1), memoryallocators(9)
NetBSD 7.1.1 August 7, 2015 NetBSD 7.1.1
Powered by man-cgi (2024-08-24).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.