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

FreeBSD Manual Pages


home | help
malloc(3C)							    malloc(3C)

       malloc,	calloc,	free, memalign,	realloc, valloc, alloca	- memory allo-

       #include	<stdlib.h>

       void *malloc(size_t size);

       void *calloc(size_t nelem, size_t elsize);

       void free(void *ptr);

       void *memalign(size_t alignment,	size_t size);

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

       void *valloc(size_t size);

       #include	<alloca.h>

       void *alloca(size_t size);

       The malloc() and	free() functions  provide  a  simple,  general-purpose
       memory allocation package. The malloc() function	returns	a pointer to a
       block of	at least size bytes suitably aligned for any use. If the space
       assigned	by malloc() is overrun,	the results are	undefined.

       The  argument to	free() is a pointer to a block previously allocated by
       malloc(), calloc(), or realloc(). After free() is executed, this	 space
       is made available for further allocation	by the application, though not
       returned	to the system. Memory is returned to the system	only upon ter-
       mination	 of  the application. If  ptr is a null	pointer, no action oc-
       curs. If	a random number	is passed to free(),  the  results  are	 unde-

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

       The memalign() function allocates size bytes on a  specified  alignment
       boundary	and returns a pointer to the allocated block. The value	of the
       returned	address	is guaranteed to be an even multiple of	alignment. The
       value  of  alignment must be a power of two and must be greater than or
       equal to	the size of a word.

       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 valloc() function has the same effect as malloc(), except that  the
       allocated memory	will be	aligned	to a multiple of the value returned by

       The alloca() function allocates size bytes of space in the stack	 frame
       of  the caller, and returns a pointer to	the allocated block. This tem-
       porary space is automatically freed when	the caller returns. If the al-
       located block is	beyond the current stack limit,	the resulting behavior
       is undefined.

       Upon successful completion, each	of the allocation functions returns  a
       pointer to space	suitably aligned (after	possible pointer coercion) for
       storage of any type of object.

       If there	is no available	memory,	malloc(), realloc(), memalign(),  val-
       loc(),  and  calloc()  return  a	null pointer. When realloc() is	called
       with size > 0 and returns NULL, the block pointed to by ptr is left in-
       tact. If	size, nelem, or	elsize is 0, either a null pointer or a	unique
       pointer that can	be passed to free() is returned.

       If malloc(), calloc(), or realloc() returns unsuccessfully, errno  will
       be set to indicate the error. The free()	function does not set errno.

       The malloc(), calloc(), and realloc() functions will fail if:

       ENOMEM	       The  physical limits of the system are exceeded by size
		       bytes of	memory which cannot be allocated.

       EAGAIN	       There is	not enough memory available to	allocate  size
		       bytes  of  memory;  but the application could try again

       Portable	applications should avoid using	valloc()  but  should  instead
       use  malloc() or	mmap(2). On systems with a large page size, the	number
       of successful valloc() operations might be 0.

       These default memory allocation routines	are safe  for  use  in	multi-
       threaded	applications but are not scalable. Concurrent accesses by mul-
       tiple threads are single-threaded through the use  of  a	 single	 lock.
       Multithreaded  applications that	make heavy use of dynamic memory allo-
       cation should be	linked with allocation libraries designed for  concur-
       rent  access,  such as libumem(3LIB) or libmtmalloc(3LIB). Applications
       that want to avoid using	heap allocations (with brk(2)) can  do	so  by
       using  either  libumem  or libmapmalloc(3LIB). The allocation libraries
       libmalloc(3LIB) and libbsdmalloc(3LIB) are available for	special	needs.

       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	   |
       |Interface Stability	     |See below.		   |
       |MT-Level		     |Safe			   |

       The malloc(), calloc(), free(), realloc(), valloc() functions are Stan-
       dard. The memalign() and	alloca() functions are Stable.

       brk(2), getrlimit(2), libbsdmalloc(3LIB),  libmalloc(3LIB),  libmapmal-
       loc(3LIB),   libmtmalloc(3LIB),	 libumem(3LIB),	  umem_alloc(3MALLOC),
       watchmalloc(3MALLOC), attributes(5)

       Undefined results will occur if the size	requested for a	block of  mem-
       ory exceeds the maximum size of a process's heap, which can be obtained
       with getrlimit(2)

       The alloca() function is	machine-, compiler-, and most of all,  system-
       dependent. Its use is strongly discouraged.

				  21 Mar 2005			    malloc(3C)


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

home | help