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

FreeBSD Manual Pages

  
 
  

home | help
MALLOC(3)		 BSD Library Functions Manual		     MALLOC(3)

NAME
     malloc, calloc, realloc, free -- general purpose memory allocation	func-
     tions

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <stdlib.h>

     void *
     malloc(size_t size);

     void *
     calloc(size_t number, size_t size);

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

     void
     free(void *ptr);

DESCRIPTION
     The malloc() function allocates size bytes	of uninitialized memory.  The
     allocated space is	suitably aligned (after	possible pointer coercion) for
     storage of	any type of object.

     The calloc() function allocates space for number objects, each size bytes
     in	length.	 The result is identical to calling malloc() with an argument
     of	"number	* size", with the exception that the allocated memory is ex-
     plicitly initialized to zero bytes.

     The realloc() function changes the	size of	the previously allocated mem-
     ory referenced by ptr to size bytes.  The contents	of the memory are un-
     changed up	to the lesser of the new and old sizes.	 If the	new size is
     larger, the value of the newly allocated portion of the memory is unde-
     fined.  Upon success, the memory referenced by ptr	is freed and a pointer
     to	the newly allocated memory is returned.	 Note that realloc() may move
     the memory	allocation, resulting in a different return value than ptr.
     If	ptr is NULL, the realloc() function behaves identically	to malloc()
     for the specified size.

     The free()	function causes	the allocated memory referenced	by ptr to be
     made available for	future allocations.  If	ptr is NULL, no	action occurs.

RETURN VALUES
     The malloc() and calloc() functions return	a pointer to the allocated
     memory if successful; otherwise a NULL pointer is returned	and errno is
     set to ENOMEM.

     The realloc() function returns a pointer, possibly	identical to ptr, to
     the allocated memory if successful; otherwise a NULL pointer is returned,
     and errno is set to ENOMEM	if the error was the result of an allocation
     failure.  The realloc() function always leaves the	original buffer	intact
     when an error occurs.

     The free()	function returns no value.

EXAMPLES
     When using	malloc(), be careful to	avoid the following idiom:

	   if ((p = malloc(number * size)) == NULL)
		   err(EXIT_FAILURE, "malloc");

     The multiplication	may lead to an integer overflow.  To avoid this,
     calloc() is recommended.

     If	malloc() must be used, be sure to test for overflow:

	   if (size && number >	SIZE_MAX / size) {
		   errno = EOVERFLOW;
		   err(EXIT_FAILURE, "allocation");
	   }

     When using	realloc(), one must be careful to avoid	the following idiom:

	   nsize += 50;

	   if ((p = realloc(p, nsize)) == NULL)
		   return NULL;

     Do	not adjust the variable	describing how much memory has been allocated
     until it is known that the	allocation has been successful.	 This can
     cause aberrant program behavior if	the incorrect size value is used.  In
     most cases, the above example will	also leak memory.  As stated earlier,
     a return value of NULL indicates that the old object still	remains	allo-
     cated.  Better code looks like this:

	   newsize = size + 50;

	   if ((p2 = realloc(p,	newsize)) == NULL) {

		   if (p != NULL)
			   free(p);

		   p = NULL;
		   return NULL;
	   }

	   p = p2;
	   size	= newsize;

SEE ALSO
     madvise(2), mmap(2), sbrk(2), alloca(3), atexit(3), getpagesize(3),
     memory(3),	posix_memalign(3)

     For the implementation details, see jemalloc(3).

STANDARDS
     The malloc(), calloc(), realloc() and free() functions conform to ISO/IEC
     9899:1990 ("ISO C90").

BSD				  May 3, 2010				   BSD

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | SEE ALSO | STANDARDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=malloc&sektion=3&manpath=NetBSD+6.0>

home | help