MALLOC(9r)																MALLOC(9r)

NAME

       MALLOC - General: Allocates a variable-size section of kernel virtual memory

SYNOPSIS

       #include <sys/malloc.h>

       MALLOC(
	       addr,
	       cast,
	       u_long size,
	       int type,
	       int flags );

ARGUMENTS

       Specifies  the  memory pointer that points to the allocated memory. You specify the addr argument's data type in the cast argument.  Speci-
       fies the data type of the addr argument and the type of the memory pointer returned by MALLOC.  Specifies the size in bytes of  the  memory
       to  allocate.  Typically, you pass the size as a constant to speed up the memory allocation.  Specifies the purpose for which the memory is
       being allocated.  The memory types are defined in the file <malloc.h>. Typically, kernel modules use the constant M_DEVBUF to indicate that
       kernel  module  memory  is  being allocated (or freed).	Specifies one of the following flag constants defined in /usr/sys/include/sys/mal-
       loc.h: Allocates memory from the virtual memory subsystem if there is not enough memory in the preallocated pool. This  constant  signifies
       that  MALLOC can block.	Does not allocate memory from the virtual memory subsystem if there is not enough memory in the preallocated pool.
       This constant signifies that MALLOC cannot block.  Allocates zero-filled memory. You pass this  bit  value  by  ORing  it  to  M_WAITOK	or
       M_NOWAIT.

DESCRIPTION

       The  MALLOC  routine (macro) allocates at least size bytes from the kernel memory and returns the address of the allocated memory. A kernel
       module can allocate the memory in interrupt and process contexts.

       The MALLOC routine (macro) maintains a pool of preallocated memory for quick allocation. If there is not enough memory in the pool,  MALLOC
       allocates  memory from the virtual memory subsystem by calling kmem_alloc, which can potentially block (sleep). A  kernel thread that allo-
       cates and frees memory to and from the preallocated pool.

       The MALLOC routine (macro) is actually a wrapper that calls malloc. A kernel module should not directly call the MALLOC routine.

       The type argument allows the memory allocator to keep track of memory usage by a subsystem.

       If the allocation size is greater than 16K, you must pass M_WAITOK to the flags argument. You cannot allocate more than 16K bytes of memory
       in interrupt context.

NOTES

       A  memory  corruption  can  occur if a device driver continues to use the memory after freeing it. The operating system provides a built-in
       mechanism to debug such erroneous use of memory. You can enable this debugging feature at boot time by providing the following boot parame-
       ter: kmem_debug=1. When you enable this debugging feature, the FREE routine stores the following in the last word of freed memory: The pro-
       gram counter (pc) of the module that last freed the memory The checksum of the memory content

       The MALLOC routine checks the checksum of the memory content before reallocating this corrupted memory. If the checksum of the memory  con-
       tent  does  not	match  the  corrupted  memory, MALLOC stores the debug information and then causes the kernel to panic. The MALLOC routine
       stores the address and size of the corrupted memory and the pc of the routine that last freed it in a kmem_corrupt_data structure.

       You should consider the following when using this debugging feature: This debugging feature does not  detect  cases  where  the	corruption
       occurs  after  MALLOC reallocates the freed memory to some other module.  There is a small chance that the pc of the routine that freed the
       memory (stored in the last word of freed memory) may itself become corrupted.

CAUTIONS

       A device driver must not call MALLOC in interrupt context with the flags argument set to M_WAITOK. If flags  is	set  to  M_WAITOK,  MALLOC
       checks if the kernel thread is in interrupt context. If so, MALLOC returns a null pointer and displays a message on the console terminal.

       The M_WAITOK flag implies that it is valid to allocate memory from the virtual memory subsystem if there is not enough memory in the preal-
       located pool. To be able to allocate memory from the virtual memory subsystem (which can page fault), the device driver must be in  process
       context.

RETURN VALUES

       Upon successful completion, MALLOC returns the address of the allocated memory. The return type associated with this address is the same as
       that specified for the addr argument.  If the memory allocation request cannot be fulfilled, MALLOC returns a  null  pointer  in  the  addr
       argument.

SEE ALSO

       Routines: FREE(9r)

																	MALLOC(9r)