REALLOCARR(3)

REALLOCARR(3) | Library Functions Manual | REALLOCARR(3)

# NAME

`reallocarr` — reallocate array

# SYNOPSIS

`#include <stdlib.h>`

int
`reallocarr`(void *ptrp, size_t number, size_t size);

# DESCRIPTION

The `reallocarr` function safely allocates, resizes, or frees arrays in memory.

If ptr is a null pointer, or a pointer to memory previously allocated with `reallocarr`, then `reallocarr`(`&`ptr, number, size); allocates or reallocates the memory that ptr points to, possibly moving it to a different location in memory, so that it has space for an array of number elements of size bytes apiece. `reallocarr` updates ptr in case it was moved on success, and leaves it unchanged on failure.

If ptr was previously allocated, the objects stored at ptr`[0]`, ptr`[1]`, ..., up to the shorter of its old number and its new number, are copied into the new memory, like realloc(3).

ptr may be null and number may be zero. size must be nonzero.

The memory allocated by `reallocarr` may be freed with `reallocarr`(`&`ptr, `0`, size);, which will always succeed and unconditionally set ptr to null.

Like calloc(3), `reallocarr` fails gracefully if the product of number and size would overflow the representable size of memory. Unlike calloc(3), new memory allocated by `reallocarr` is not zero-initialized.

The `reallocarr` function may alter errno as a side effect.

Note that the argument ptrp is a pointer to a pointer to allocated memory, unlike realloc(3) which takes a pointer to allocated memory.

# RETURN VALUES

On successful completion, `reallocarr` returns 0 and updates ptr. Otherwise, an errno(2) is returned, and ptr and the memory it points to are unmodified.

# EXAMPLES

The following uses `reallocarr`() to initialize an array of `INITSIZE` integers, then resizes it to `NEWSIZE` elements, and finally frees it:

    int *data = NULL;
    int error = 0;

    /* allocate */
    error = reallocarr(&data, INITSIZE, sizeof(*data));
    if (error)
    	errc(1, error, "reallocarr failed");
    ...
    /* resize */
    error = reallocarr(&data, NEWSIZE, sizeof(*data));
    if (error)
    	errc(1, error, "reallocarr failed on resize");
    ...
    /* free */
    (void)reallocarr(&data, 0, sizeof(*data));
    assert(data == NULL);

# SEE ALSO

calloc(3), realloc(3), reallocarray(3)

# HISTORY

`reallocarr` first appeared in NetBSD 7.0. OpenBSD introduced the reallocarray(3) function for the same purpose, but the interface makes it difficult to correctly handle zero-sized allocations.

August 31, 2022 | NetBSD 11.0