Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
malloc(3MALLOC)						       malloc(3MALLOC)

       malloc, free, realloc, calloc, mallopt, mallinfo	- memory allocator

       cc [ flag ... ] file ...	-lmalloc [ library ... ]
       #include	<stdlib.h>

       void *malloc(size_t size);

       void free(void *ptr);

       void *realloc(void *ptr,	size_t size);

       void *calloc(size_t nelem, size_t elsize);

       #include	<malloc.h>

       int mallopt(int cmd, int	value);

       struct mallinfo mallinfo(void);

       The malloc() and	free() functions provide a simple general-purpose mem-
       ory allocation package.

       The malloc() function returns a pointer to a block  of  at  least  size
       bytes suitably aligned for any use.

       The  argument to	free() is a pointer to a block previously allocated by
       malloc(). After free() is performed, this space is made	available  for
       further allocation, and its contents have been destroyed. See mallopt()
       below for a way to change this behavior.	If ptr is a null  pointer,  no
       action occurs.

       Undefined results occur if the space assigned by	malloc() is overrun or
       if some random number is	handed to free().

       The free() function does	not set	errno.

       The realloc() function changes the size of the block pointed to by  ptr
       to  size	bytes and returns a pointer to the (possibly moved) block. The
       contents	will be	unchanged up to	the lesser of the new and  old	sizes.
       If  the new size	of the block requires movement of the block, the space
       for the previous	instantiation of the block is freed. If	the  new  size
       is larger, the contents of the newly allocated portion of the block are
       unspecified. If ptr is NULL, realloc() behaves like  malloc()  for  the
       specified  size.	 If size is 0 and ptr is not a null pointer, the space
       pointed to is freed.

       The calloc() function allocates space for an array of nelem elements of
       size elsize. The	space is initialized to	zeros.

       The  mallopt()  function	provides for control over the allocation algo-
       rithm. The available values for cmd are:

       M_MXFAST	       Set maxfast to	value.	The  algorithm	allocates  all
		       blocks  below  the  size	of maxfast in large groups and
		       then doles them out very	quickly. The default value for
		       maxfast is 24.

       M_NLBLKS	       Set  numlblks  to  value.  The  above mentioned ``large
		       groups''	each contain numlblks blocks.	numlblks  must
		       be  greater  than  0. The default value for numlblks is

       M_GRAIN	       Set grain to  value. The	sizes of  all  blocks  smaller
		       than  maxfast  are  considered  to be rounded up	to the
		       nearest multiple	of grain. grain	must be	 greater  than
		       0. The default value of grain is	the smallest number of
		       bytes that will allow alignment of any data type. Value
		       will  be	 rounded  up to	a multiple of the default when
		       grain is	set.

       M_KEEP	       Preserve	data in	a freed	block until the	next malloc(),
		       realloc(),  or  calloc().  This option is provided only
		       for compatibility with the old version of malloc(), and
		       it is not recommended.

       These values are	defined	in the <malloc.h> header.

       The  mallopt()  function	can be called repeatedly, but cannot be	called
       after the first small block is allocated.

       The mallinfo() function provides	instrumentation	describing  space  us-
       age. It returns the mallinfo structure with the following members:

       unsigned	long arena;	 /* total space	in arena */
       unsigned	long ordblks;	 /* number of ordinary blocks */
       unsigned	long smblks;	 /* number of small blocks */
       unsigned	long hblkhd;	 /* space in holding block headers */
       unsigned	long hblks;	 /* number of holding blocks */
       unsigned	long usmblks;	 /* space in small blocks in use */
       unsigned	long fsmblks;	 /* space in free small	blocks */
       unsigned	long uordblks;	 /* space in ordinary blocks in	use */
       unsigned	long fordblks;	 /* space in free ordinary blocks */
       unsigned	long keepcost;	 /* space penalty if keep option */
				 /* is used */

       The mallinfo structure is defined in the	<malloc.h> header.

       Each  of	 the  allocation  routines returns a pointer to	space suitably
       aligned (after possible pointer coercion) for storage of	 any  type  of

       The  malloc(),  realloc(), and calloc() functions return	a null pointer
       if there	is not enough available	memory.	When realloc()	returns	 NULL,
       the  block  pointed to by ptr is	left intact. If	size, nelem, or	elsize
       is 0, either a null pointer or a	unique pointer that can	be  passed  to
       free()  is  returned. If	mallopt() is called after any allocation or if
       cmd or value are	invalid, a non-zero value is returned.	Otherwise,  it
       returns 0.

       If  malloc(),  calloc(),	or realloc() returns  unsuccessfully, errno is
       set to indicate the error:

       ENOMEM	       size bytes of memory exceeds  the  physical  limits  of
		       your system, and	cannot be allocated.

       EAGAIN	       There  is  not enough memory available at this point in
		       time to allocate	size bytes of memory; but the applica-
		       tion could try again later.

       Unlike  malloc(3C),  this  package  does	not preserve the contents of a
       block when it is	freed, unless  the M_KEEP option of mallopt() is used.

       Undocumented features of	 malloc(3C) have not been duplicated.

       Function	prototypes for malloc(), realloc(), calloc(), and  free()  are
       also defined in the <malloc.h> header for compatibility with old	appli-
       cations.	New applications  should include <stdlib.h> to access the pro-
       totypes for these functions.

       Comparative  features  of the various allocation	libraries can be found
       in the umem_alloc(3MALLOC) manual page.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |Safe			   |

       brk(2),	bsdmalloc(3MALLOC),  libmtmalloc(3LIB),	 malloc(3C),   mapmal-
       loc(3MALLOC), mtmalloc(3MALLOC),	umem_alloc(3MALLOC), watchmalloc(3MAL-
       LOC), attributes(5)

				  21 Mar 2005		       malloc(3MALLOC)


Want to link to this manual page? Use this URL:

home | help