MALLOC(9)              NetBSD Kernel Developer's Manual              MALLOC(9)

NAME
     malloc, MALLOC, realloc, free, FREE, malloc_roundup, malloc_type_attach,
     malloc_type_detach, malloc_type_setlimit, MALLOC_DEFINE_LIMIT,
     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);

     MALLOC(space, cast, 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);

     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);

DESCRIPTION
     These interfaces are being obsoleted and their new use is discouraged.
     For new code, use kmem_alloc(9) or pool_cache(9) instead.

     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 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().

     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((void *)(addr), type)

     The MALLOC() macro is intended to be used with a compile-time constant
     size so that the compiler can do constant folding.  In the comparison to
     malloc() and free() functions, the MALLOC() and FREE() macros may be
     faster, at the cost of increased code size.  There is no difference
     between the memory allocated with MALLOC and malloc.  i.e., no matter
     which MALLOC or malloc is used to allocate the memory, either FREE or
     free can be used to free it.

     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_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 mem-
     ory, 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 mal-
     loc 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.  This is intended for use by LKMs; malloc types
     included in modules statically-linked into the kernel are automatically
     registered with the kernel memory allocator.  However, it is possible to
     define malloc types without automatically registering them using
     MALLOC_JUSTDEFINE() or MALLOC_JUSTDEFINE_LIMIT().  Apart from not auto-
     matically registering to the kernel a boot time, these functions are
     equivalent to their counterparts.  They can be used when a separate LKM
     codepath for initialization is not desired.

     The malloc_type_detach() function detaches the malloc type type previ-
     ously 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:

           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.

     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'.

RETURN VALUES
     malloc() returns a kernel virtual address that is suitably aligned for
     storage of any type of object.

DIAGNOSTICS
     A kernel compiled with the DIAGNOSTIC 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 mes-
     sage:

           o   panic: ``malloc - bogus type''
           o   panic: ``malloc: out of space in kmem_map''
           o   panic: ``malloc: allocation too large''
           o   panic: ``malloc: wrong bucket''
           o   panic: ``malloc: lost data''
           o   panic: ``free: unaligned addr''
           o   panic: ``free: duplicated free''
           o   panic: ``free: multiple frees''
           o   panic: ``init: minbucket too small/struct freelist too big''
           o   ``multiply freed item <addr>''
           o   ``Data modified on freelist: <data object description>''

SEE ALSO
     vmstat(1), memoryallocators(9)

NetBSD 5.0_STABLE              December 29, 2008             NetBSD 5.0_STABLE
