MALLOC(3)

MALLOC(3) | Library Functions Manual | MALLOC(3)

# NAME

`malloc`, `calloc`, `realloc`, `free` —
general purpose memory allocation functions

# 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 explicitly initialized to zero bytes.

The `realloc`() function changes the size of the previously allocated memory referenced by ptr to size bytes. The contents of the memory are unchanged 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 undefined. 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. If size is 0, either `NULL` or a pointer that can be safely passed to free(3) is returned.

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, reallocarr(3) 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");
    }

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(size * num)) == NULL)
    	err(1, "malloc");

Assuming the implementation checks for integer overflow as NetBSD does, it is much easier to use `calloc`() or reallocarr(3).

The above examples could be simplified to:

    ptr = NULL;
    if ((e = reallocarr(&ptr, num, size)))
    	errx(1, "reallocarr", strerror(e));

    or at the cost of initialization:
    if ((p = calloc(num, size)) == NULL)
    	err(1, "calloc");

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;

# SEE ALSO

madvise(2), mmap(2), sbrk(2), aligned_alloc(3), alloca(3), atexit(3), getpagesize(3), memory(3), posix_memalign(3), reallocarr(3)

For the implementation details, see jemalloc(3).

# STANDARDS

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

# HISTORY

A `free`() internal kernel function and a predecessor to `malloc`(), `alloc`(), first appeared in Version 1 AT&T UNIX. The 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 (“phk's malloc” or “new malloc”) which appeared in FreeBSD 2.2 and was included in NetBSD 1.5 and OpenBSD 2.0. These implementations were all sbrk(2) based.

The jemalloc(3) allocator became the default system allocator first in FreeBSD 7.0 and then in NetBSD 5.0.

June 1, 2016 | NetBSD 9.0