man.bsd.lv manual page server

NAME

malloc, calloc, realloc, reallocf, free, freezero — general purpose memory allocation functions

LIBRARY

library “libc”

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 *
reallocf(void *ptr, size_t size);

void
free(void *ptr);

void
freezero(void *ptr, size_t size);

IMPLEMENTATION NOTES

DragonFly's malloc implementation is based on a port of the DragonFly kernel slab allocator, appropriately modified for a user process environment.

The slab allocator breaks memory allocations up to 8KB into 80 zones. Each zone represents a fixed allocation size in multiples of some core chunking. The chunking is a power-of-2 but the fixed allocation size is not. For example, a 1025-byte request is allocated out of the zone with a chunking of 128, thus in multiples of 1152 bytes. The minimum chunking, used for allocations in the 0-127 byte range, is 8 bytes (16 of the 80 zones). Beyond that the power-of-2 chunking is between 1/8 and 1/16 of the minimum allocation size for any given zone.

As a special case any power-of-2-sized allocation within the zone limit (8K) will be aligned to the same power-of-2 rather than that zone's (smaller) chunking. This is not something you can depend upon for malloc(), but it is used internally to optimize posix_memalign(3).

Each zone reserves memory in 64KB blocks. Actual memory use tends to be significantly less as only the pages actually needed are faulted in. Allocations larger than 8K are managed using mmap(2) and tracked with a hash table.

The zone mechanism results in well-fitted allocations with little waste in a long-running environment which makes a lot of allocations. Short-running environments which do not make many allocations will see a bit of extra bloat due to the large number of zones but it will be almost unnoticeable in the grand scheme of things. To reduce bloat further the normal randomized start offset implemented in the kernel version of the allocator to improve L1 cache fill is disabled in the libc version.

The zone mechanism also has the nice side effect of greatly reducing fragmentation over the original malloc.

calloc() is directly supported by keeping track of newly-allocated zones which will be demand-zero'd by the system. If the allocation is known to be zero'd we do not bother bzero()ing it. If it is a reused allocation we bzero().

POSIX threading is supported by duplicating the primary structure. A thread entering malloc() which is unable to immediately acquire a mutex on the last primary structure it used will switch to a different primary structure. At the moment this is more of a quick hack than a solution, but it works.

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() and reallocf() functions return 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, whereas reallocf() deallocates it in this case.

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 allocated. 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;

RETURN VALUES

If malloc(), calloc(), realloc() or free() detect an error, a message will be printed to file descriptor STDERR_FILENO and the process will dump core.

SEE ALSO

madvise(2), mmap(2), sbrk(2), alloca(3), atexit(3), emalloc(3), getpagesize(3), memory(3), posix_memalign(3), reallocarray(3)

STANDARDS

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

HISTORY

The reallocf() function first appeared in FreeBSD 3.0.

The freezero() function appeared in OpenBSD 6.2 and DragonFly 5.5.

DragonFly's malloc implementation is based on the kernel's slab allocator (see posix_memalign(3)'s IMPLEMENTATION NOTES). It first appeared in DragonFly 2.3.

AUTHORS

Matt Dillon