MALLOC(9) | Kernel Developer's Manual | MALLOC(9) |
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);
unsigned long
malloc_roundup(unsigned long size);
void
malloc_type_attach(struct malloc_type *type);
void
malloc_type_detach(struct malloc_type *type);
void
malloc_type_setlimit(struct malloc_type *type, unsigned long limit);
#include <sys/mallocvar.h>
MALLOC_DEFINE_LIMIT(type, shortdesc, longdesc, limit);
MALLOC_JUSTDEFINE_LIMIT(type, shortdesc, longdesc, limit);
MALLOC_DEFINE(type, shortdesc, longdesc);
MALLOC_JUSTDEFINE(type, shortdesc, longdesc);
MALLOC_DECLARE(type);
The malloc() function allocates uninitialized memory in kernel address space for an object whose size is specified by size. malloc_roundup() returns the actual size of the allocation unit for the given value. 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 memory 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:
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 maintain 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_LIMIT() 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 argument, 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. The limit argument specifies the maximum amount of memory, in bytes, that this malloc type can consume.
The MALLOC_DEFINE() macro is equivalent to the MALLOC_DEFINE_LIMIT() macro with a limit argument of 0. 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 necessary extern declaration.
Code which includes <sys/malloc.h> does not need to include <sys/mallocvar.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 previously attached with malloc_type_attach().
The malloc_type_setlimit() function sets the memory limit of the malloc type type to limit bytes. The type must already be registered with the kernel memory allocator.
The following generic malloc types are currently defined:
Other malloc types are defined by the corresponding subsystem; see the documentation for that subsystem for information its available malloc types.
Statistics based on the type argument are maintained only if the kernel option KMEMSTATS is used when compiling the kernel (the default in current NetBSD kernels) and can be examined by using ‘vmstat -m'.
December 29, 2008 | NetBSD 6.1 |