Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

MALLOC(9)                  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
     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:

           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.

     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() 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.  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 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_TEMP          Misc temporary data buffers.

     Other malloc types are defined by the corresponding subsystem; see the
     documentation for that subsystem for information about its available
     malloc types.

NOTES
     The malloc type argument is actually unused on NetBSD, the argument is
     only supported for easier source compatibility with FreeBSD and OpenBSD.
     Likewise calls to MALLOC_DECLARE(), MALLOC_DEFINE(),
     malloc_type_attach(), and malloc_type_detach() are defined out and have
     no effect on NetBSD.

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 10.99                    January 4, 2021                   NetBSD 10.99