home | help
MALLOC(9)		    Kernel Developer's Manual		       MALLOC(9)

NAME
     malloc,	MALLOC,    free,   FREE,   realloc,   reallocf,   MALLOC_DEFINE,
     MALLOC_DECLARE -- kernel memory management routines

SYNOPSIS
     #include <sys/types.h>
     #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
     free(void *addr, struct malloc_type *type);

     FREE(void *addr, struct malloc_type *type);

     void *
     realloc(void *addr, unsigned long size, struct malloc_type *type,
	 int flags);

     void *
     reallocf(void *addr, unsigned long size, struct malloc_type *type,
	 int flags);

     MALLOC_DECLARE(type);

     #include <sys/param.h>
     #include <sys/malloc.h>
     #include <sys/kernel.h>

     MALLOC_DEFINE(type, shortdesc, longdesc);

DESCRIPTION
     The malloc() function allocates  uninitialized  memory  in  kernel  address
     space for an object whose size is specified by size.

     The free() function releases memory at address addr that was previously al-
     located  by  malloc()  for  re-use.   The memory is not zeroed.  If addr is
     NULL, then free() does nothing.

     The realloc() function changes the size of the previously allocated  memory
     referenced by addr to size bytes.	The contents of the memory are unchanged
     up  to  the  lesser of the new and old sizes.  Note that the returned value
     may differ from addr.  If the requested memory cannot be allocated, NULL is
     returned and the memory referenced by addr is valid and unchanged.  If addr
     is NULL, the realloc() function behaves identically  to  malloc()	for  the
     specified size.

     The  reallocf() function is identical to realloc() except that it will free
     the passed pointer when the requested memory cannot be allocated.

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

     Unlike its standard C library counterpart (malloc(3)), the  kernel  version
     takes  two more arguments.  The flags argument further qualifies malloc()'s
     operational characteristics as follows:

     M_ZERO  Causes the allocated memory to be set to all zeros.

     M_NOWAIT
	     Causes malloc(), realloc(), and reallocf() to return  NULL  if  the
	     request  cannot  be immediately fulfilled due to resource shortage.
	     Note that M_NOWAIT is required when running in  an  interrupt  con-
	     text.

     M_WAITOK
	     Indicates that it is OK to wait for resources.  If the request can-
	     not  be  immediately fulfilled, the current process is put to sleep
	     to wait for resources to be released by other processes.  The  mal-
	     loc(),  realloc(),  and  reallocf() functions cannot return NULL if
	     M_WAITOK is specified.

     M_USE_RESERVE
	     Indicates that the system can dig into its reserve in order to  ob-
	     tain  the requested memory.  This option used to be called M_KERNEL
	     but has been renamed to something more obvious.   This  option  has
	     been deprecated and is slowly being removed from the kernel, and so
	     should not be used with any new programming.

     Exactly one of either M_WAITOK or M_NOWAIT must be specified.

     The  type	argument  is used to perform statistics on memory usage, and for
     basic sanity checks.  It can be used to identify multiple allocations.  The
     statistics can be examined by `vmstat -m'.

     A type is defined using struct malloc_type  via  the  MALLOC_DECLARE()  and
     MALLOC_DEFINE() macros.

	   /* sys/something/foo_extern.h */

	   MALLOC_DECLARE(M_FOOBUF);

	   /* sys/something/foo_main.c */

	   MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");

	   /* sys/something/foo_subr.c */

	   ...
	   MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);

     In order to use MALLOC_DEFINE(), one must include <sys/param.h> (instead of
     <sys/types.h>) and <sys/kernel.h>.

IMPLEMENTATION NOTES
     The  memory  allocator allocates memory in chunks that have size a power of
     two for requests up to the size of a page of memory.  For larger  requests,
     one  or  more pages is allocated.	While it should not be relied upon, this
     information may be useful for optimizing the efficiency of memory use.

     Programmers should be careful not to confuse the malloc flags M_NOWAIT  and
     M_WAITOK with the mbuf(9) flags M_DONTWAIT and M_TRYWAIT.

CONTEXT
     malloc(),	realloc()  and reallocf() may not be called from fast interrupts
     handlers.	 When  called  from  threaded  interrupts,  flags  must  contain
     M_NOWAIT.

     malloc(),	realloc()  and	reallocf()  may sleep when called with M_WAITOK.
     free() never sleeps.

     Any calls to malloc() (even with M_NOWAIT) or free()  when  holding  a  vn-
     ode(9)  interlock, will cause a LOR (Lock Order Reversal) due to the inter-
     twining of VM Objects and Vnodes.

RETURN VALUES
     The malloc(), realloc(), and reallocf() functions return a  kernel  virtual
     address that is suitably aligned for storage of any type of object, or NULL
     if the request could not be satisfied (implying that M_NOWAIT was set).

DIAGNOSTICS
     A	kernel compiled with the INVARIANTS configuration option attempts to de-
     tect memory corruption caused by such things as writing outside  the  allo-
     cated  area  and  imbalanced  calls  to  the malloc() and free() functions.
     Failing consistency checks will cause a panic or a system console message.

SEE ALSO
     vmstat(8), contigmalloc(9), memguard(9), vnode(9)

FreeBSD 7.0			  June 12, 2003 		       MALLOC(9)

home | help