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

FreeBSD Manual Pages

  
 
  

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

NAME
     malloc, calloc, realloc, free, reallocarray, recallocarray, freezero,
     aligned_alloc, malloc_conceal, calloc_conceal -- memory allocation	and
     deallocation

SYNOPSIS
     #include <stdlib.h>

     void *
     malloc(size_t size);

     void *
     calloc(size_t nmemb, size_t size);

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

     void
     free(void *ptr);

     void *
     reallocarray(void *ptr, size_t nmemb, size_t size);

     void *
     recallocarray(void	*ptr, size_t oldnmemb, size_t nmemb, size_t size);

     void
     freezero(void *ptr, size_t	size);

     void *
     aligned_alloc(size_t alignment, size_t size);

     void *
     malloc_conceal(size_t size);

     void *
     calloc_conceal(size_t nmemb, size_t size);

     char *malloc_options;

DESCRIPTION
     The standard functions malloc(), calloc(),	and realloc() allocate
     objects, regions of memory	to store values.  The malloc() function	allo-
     cates uninitialized space for an object of	the specified size.  malloc()
     maintains multiple	lists of free objects according	to size, allocating
     from the appropriate list or requesting memory from the kernel.  The al-
     located space is suitably aligned (after possible pointer coercion) for
     storage of	any type of object.

     The calloc() function allocates space for an array	of nmemb objects, each
     of	the specified size.  The space is initialized to zero.

     The realloc() function changes the	size of	the object pointed to by ptr
     to	size bytes and returns a pointer to the	(possibly moved) object.  If
     ptr is not	NULL, it must be a pointer returned by an earlier call to an
     allocation	or reallocation	function that was not freed in between.	 The
     contents of the object are	unchanged up to	the lesser of the new and old
     sizes.  If	the new	size is	larger,	the value of the newly allocated por-
     tion of the object	is indeterminate and uninitialized.  If	the space can-
     not be allocated, the object pointed to by	ptr is unchanged.  If ptr is
     NULL, realloc() behaves like malloc() and allocates a new object.

     The free()	function causes	the space pointed to by	ptr to be either
     placed on a list of free blocks to	make it	available for future alloca-
     tion or, when appropriate,	to be returned to the kernel using munmap(2).
     If	ptr is NULL, no	action occurs.	If ptr was previously freed by free()
     or	a reallocation function, the behavior is undefined and the double free
     is	a security concern.

     Designed for safe allocation of arrays, the reallocarray()	function is
     similar to	realloc() except it operates on	nmemb members of size size and
     checks for	integer	overflow in the	calculation nmemb * size.

     Used for the allocation of	memory holding sensitive data, the
     recallocarray() and freezero() functions guarantee	that memory becoming
     unallocated is explicitly discarded, meaning pages	of memory are disposed
     via munmap(2) and cached free objects are cleared with explicit_bzero(3).

     The recallocarray() function is similar to	reallocarray() except it en-
     sures newly allocated memory is cleared similar to	calloc().  If ptr is
     NULL, oldnmemb is ignored and the call is equivalent to calloc().	If ptr
     is	not NULL, oldnmemb must	be a value such	that oldnmemb *	size is	the
     size of the earlier allocation that returned ptr, otherwise the behavior
     is	undefined.

     The freezero() function is	similar	to the free() function except it en-
     sures memory is explicitly	discarded.  If ptr is NULL, no action occurs.
     If	ptr is not NULL, the size argument must	be equal to or smaller than
     the size of the earlier allocation	that returned ptr.  freezero() guaran-
     tees the memory range starting at ptr with	length size is discarded while
     deallocating the whole object originally allocated.

     The aligned_alloc() function allocates size bytes of memory such that the
     allocation's base address is a multiple of	alignment.  The	requested
     alignment must be a power of 2.  If size is not a multiple	of alignment,
     behavior is undefined.

     The malloc_conceal() and calloc_conceal() functions behave	the same as
     malloc() and calloc() respectively, with the exception that the alloca-
     tion returned is marked with the MAP_CONCEAL mmap(2) flag and calling
     free() on the allocation will discard the contents	explicitly.  A reallo-
     cation of a concealed allocation will leave these properties intact.

MALLOC OPTIONS
     Upon the first call to the	malloc() family	of functions, an initializa-
     tion sequence inspects the	value of the vm.malloc_conf sysctl(2), next
     checks the	environment for	a variable called MALLOC_OPTIONS, and finally
     looks at the global variable malloc_options in the	program.  Each is
     scanned for the flags documented below.  Unless otherwise noted uppercase
     means on, lowercase means off.  During initialization, flags occurring
     later modify the behaviour	that was requested by flags processed earlier.

     C	     "Canaries".  Add canaries at the end of allocations in order to
	     detect heap overflows.  The canary's content is checked when free
	     is	called.	 If it has been	corrupted, the process is aborted.

     D	     "Dump".  malloc() will dump statistics to the file	./malloc.out,
	     if	it already exists, at exit.  This option requires the library
	     to	have been compiled with	-DMALLOC_STATS in order	to have	any
	     effect.

     F	     "Freecheck".  Enable more extensive double	free and use after
	     free detection.  All chunks in the	delayed	free list will be
	     checked for double	frees.	Unused pages on	the freelist are read
	     and write protected to cause a segmentation fault upon access.

     G	     "Guard".  Enable guard pages.  Each page size or larger alloca-
	     tion is followed by a guard page that will	cause a	segmentation
	     fault upon	any access.

     J	     "More junking".  Increase the junk	level by one if	it is smaller
	     than 2.

     j	     "Less junking".  Decrease the junk	level by one if	it is larger
	     than 0.  Junking writes some junk bytes into the area allocated.
	     Junk is bytes of 0xdb when	allocating; freed chunks are filled
	     with 0xdf.	 By default the	junk level is 1: after free, small
	     chunks are	completely junked; for pages the first part is junked.
	     After a delay, the	filling	pattern	is validated and the process
	     is	aborted	if the pattern was modified.  For junk level 2,	junk-
	     ing is done on allocation as well and without size	restrictions.
	     If	the junk level is zero,	no junking is performed.

     R	     "realloc".	 Always	reallocate when	realloc() is called, even if
	     the initial allocation was	big enough.

     S	     Enable all	options	suitable for security auditing.

     U	     "Free unmap".  Enable use after free protection for larger	allo-
	     cations.  Unused pages on the freelist are	read and write pro-
	     tected to cause a segmentation fault upon access.

     X	     "xmalloc".	 Rather	than return failure, abort(3) the program with
	     a diagnostic message on stderr.  It is the	intention that this
	     option be set at compile time by including	in the source:

		   extern char *malloc_options;
		   malloc_options = "X";

	     Note that this will cause code that is supposed to	handle out-of-
	     memory conditions gracefully to abort instead.

     <	     "Halve the	cache size".  Decrease the size	of the free page cache
	     by	a factor of two.

     >	     "Double the cache size".  Increase	the size of the	free page
	     cache by a	factor of two.

     If	a program changes behavior if any of these options (except X) are
     used, it is buggy.

     The default size of the cache is 64 single	page allocations.  It also
     caches a number of	larger regions.	 Multi-threaded	programs use multiple
     pools.

RETURN VALUES
     Upon successful completion, the allocation	functions return a pointer to
     the allocated space; otherwise, NULL is returned and errno	is set to
     ENOMEM.  The function aligned_alloc() returns NULL	and sets errno to
     EINVAL if alignment is not	a power	of 2.

     If	nmemb or size is equal to 0, a unique pointer to an access protected,
     zero sized	object is returned.  Access via	this pointer will generate a
     SIGSEGV exception.

     If	multiplying nmemb and size results in integer overflow,	calloc(),
     reallocarray() and	recallocarray()	return NULL and	set errno to ENOMEM.

     If	ptr is not NULL	and multiplying	oldnmemb and size results in integer
     overflow recallocarray() returns NULL and sets errno to EINVAL.

IDIOMS
     Consider calloc() or the extensions reallocarray()	and recallocarray()
     when there	is multiplication in the size argument of malloc() or
     realloc().	 For example, avoid this common	idiom as it may	lead to	inte-
     ger overflow:

	   if ((p = malloc(num * size))	== NULL)
		   err(1, NULL);

     A drop-in replacement is the OpenBSD extension reallocarray():

	   if ((p = reallocarray(NULL, num, size)) == NULL)
		   err(1, NULL);

     Alternatively, calloc() may be used at the	cost of	initialization over-
     head.

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

	   size	+= 50;
	   if ((p = realloc(p, size)) == NULL)
		   return (NULL);

     Do	not adjust the variable	describing how much memory has been allocated
     until the allocation has been successful.	This can cause aberrant	pro-
     gram behavior if the incorrect size value is used.	 In most cases,	the
     above sample will also result in a	leak of	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 ((newp = realloc(p, newsize)) == NULL) {
		   free(p);
		   p = NULL;
		   size	= 0;
		   return (NULL);
	   }
	   p = newp;
	   size	= newsize;

     As	with malloc(), it is important to ensure the new size value will not
     overflow; i.e. avoid allocations like the following:

	   if ((newp = realloc(p, num *	size)) == NULL)	{
		   ...

     Instead, use reallocarray():

	   if ((newp = reallocarray(p, num, size)) == NULL) {
		   ...

     Calling realloc() with a NULL ptr is equivalent to	calling	malloc().  In-
     stead of this idiom:

	   if (p == NULL)
		   newp	= malloc(newsize);
	   else
		   newp	= realloc(p, newsize);

     Use the following:

	   newp	= realloc(p, newsize);

     The recallocarray() function should be used for resizing objects contain-
     ing sensitive data	like keys.  To avoid leaking information, it guaran-
     tees memory is cleared before placing it on the internal free list.  De-
     allocation	of such	an object should be done by calling freezero().

ENVIRONMENT
     MALLOC_OPTIONS  String of option flags.

EXAMPLES
     If	malloc() must be used with multiplication, be sure to test for over-
     flow:

	   size_t num, size;
	   ...

	   /* Check for	size_t overflow	*/
	   if (size && num > SIZE_MAX /	size)
		   errc(1, EOVERFLOW, "overflow");

	   if ((p = malloc(num * size))	== NULL)
		   err(1, NULL);

     The above test is not sufficient in all cases.  For example, multiplying
     ints requires a different set of checks:

	   int num, size;
	   ...

	   /* Avoid invalid requests */
	   if (size < 0	|| num < 0)
		   errc(1, EOVERFLOW, "overflow");

	   /* Check for	signed int overflow */
	   if (size && num > INT_MAX / size)
		   errc(1, EOVERFLOW, "overflow");

	   if ((p = malloc(num * size))	== NULL)
		   err(1, NULL);

     Assuming the implementation checks	for integer overflow as	OpenBSD	does,
     it	is much	easier to use calloc(),	reallocarray(),	or recallocarray().

     The above examples	could be simplified to:

	   if ((p = reallocarray(NULL, num, size)) == NULL)
		   err(1, NULL);

     or	at the cost of initialization:

	   if ((p = calloc(num,	size)) == NULL)
		   err(1, NULL);

     Set a systemwide reduction	of the cache to	a quarter of the default size
     and use guard pages:

	   # sysctl vm.malloc_conf='G<<'

DIAGNOSTICS
     If	any of the functions detect an error condition,	a message will be
     printed to	file descriptor	2 (not using stdio).  Errors will result in
     the process being aborted.

     Here is a brief description of the	error messages and what	they mean:

     "out of memory"
	     If	the X option is	specified it is	an error for the allocation
	     functions to return NULL.

     "bogus pointer (double free?)"
	     An	attempt	to free() or reallocate	an unallocated pointer was
	     made.

     "chunk is already free"
	     There was an attempt to free a chunk that had already been	freed.

     "write after free"
	     A chunk has been modified after it	was freed.

     "modified chunk-pointer"
	     The pointer passed	to free() or a reallocation function has been
	     modified.

     "chunk canary corrupted address offset@length"
	     A byte after the requested	size has been overwritten, indicating
	     a heap overflow.  The offset at which corruption was detected is
	     printed before the	@, and the requested length of the allocation
	     after the @.

     "recorded old size	oldsize	!= size"
	     recallocarray() has detected that the given old size does not
	     equal the recorded	size in	its meta data.	Enabling option	C al-
	     lows recallocarray() to catch more	of these cases.

     "recursive	call"
	     An	attempt	was made to call recursively into these	functions,
	     i.e., from	a signal handler.  This	behavior is not	supported.  In
	     particular, signal	handlers should	not use	any of the malloc()
	     functions nor utilize any other functions which may call malloc()
	     (e.g., stdio(3) routines).

     "unknown char in MALLOC_OPTIONS"
	     We	found something	we didn't understand.

     any other error
	     malloc() detected an internal error; consult sources and/or wiz-
	     ards.

SEE ALSO
     brk(2), mmap(2), munmap(2), sysctl(2), alloca(3), getpagesize(3),
     posix_memalign(3)

STANDARDS
     The malloc(), calloc(), realloc(),	and free() functions conform to	ANSI
     X3.159-1989 ("ANSI	C89").	The aligned_alloc() function conforms to
     ISO/IEC 9899:2011 ("ISO C11").

     If	nmemb or size are 0, the return	value is implementation	defined; other
     conforming	implementations	may return NULL	in this	case.

     The MALLOC_OPTIONS	environment variable, the vm.malloc_conf sysctl	and
     the DIAGNOSTICS output are	extensions to the standard.

HISTORY
     A free() internal kernel function and a predecessor to malloc(), alloc(),
     first appeared in Version 1 AT&T UNIX.  C library functions alloc() and
     free() appeared in	Version	6 AT&T UNIX.  The functions malloc(),
     calloc(), and realloc() first appeared in Version 7 AT&T UNIX.

     A new implementation by Chris Kingsley was	introduced in 4.2BSD, followed
     by	a complete rewrite by Poul-Henning Kamp	which appeared in FreeBSD 2.2
     and was included in OpenBSD 2.0.  These implementations were all sbrk(2)
     based.  In	OpenBSD	3.8, Thierry Deval rewrote malloc to use the mmap(2)
     system call, making the page addresses returned by	malloc random.	A re-
     write by Otto Moerbeek introducing	a new central data structure and more
     randomization appeared in OpenBSD 4.4.

     The reallocarray()	function appeared in OpenBSD 5.6.  The recallocarray()
     function appeared in OpenBSD 6.1.	The freezero() function	appeared in
     OpenBSD 6.2.  The aligned_alloc() function	appeared in OpenBSD 6.5.  The
     malloc_conceal() and calloc_conceal() functions appeared in OpenBSD 6.6.

CAVEATS
     When using	malloc(), be wary of signed integer and	size_t overflow	espe-
     cially when there is multiplication in the	size argument.

     Signed integer overflow will cause	undefined behavior which compilers
     typically handle by wrapping back around to negative numbers.  Depending
     on	the input, this	can result in allocating more or less memory than in-
     tended.

     An	unsigned overflow has defined behavior which will wrap back around and
     return less memory	than intended.

     A signed or unsigned integer overflow is a	security risk if less memory
     is	returned than intended.	 Subsequent code may corrupt the heap by writ-
     ing beyond	the memory that	was allocated.	An attacker may	be able	to
     leverage this heap	corruption to execute arbitrary	code.

     Consider using calloc(), reallocarray() or	recallocarray()	instead	of us-
     ing multiplication	in malloc() and	realloc() to avoid these problems on
     OpenBSD.

FreeBSD	13.0			 April 9, 2021			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | MALLOC OPTIONS | RETURN VALUES | IDIOMS | ENVIRONMENT | EXAMPLES | DIAGNOSTICS | SEE ALSO | STANDARDS | HISTORY | CAVEATS

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

home | help