reallocarray(3bsd)

✨ reallocarray — the manual page bestie 💖

okay so real talk: this is reallocarray(3bsd), from the LOCAL manual, and it's the glow-up your memory allocation game has been begging for. three little functions — reallocarray, recallocarray, freezero — and they're all about memory allocation and deallocation, but like, safely. no cap. 🫶

---

🌸 NAME 🌸

reallocarray, recallocarray, freezero — memory allocation and deallocation 💅

---

📚 LIBRARY 📚

Utility functions from BSD systems (libbsd, -lbsd)

---

✨ SYNOPSIS ✨

#include <stdlib.h>
(See libbsd(7) for include usage.)

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);

ngl, that (See libbsd(7) for include usage.) line is literally part of the synopsis. it's giving "check the libbsd manpage for how to actually include this" 🧚

---

💖 DESCRIPTION 💖

so, reallocarray() was designed for the safe allocation of arrays, and it's basically realloc() but with ✨self-awareness✨. instead of just one size, it operates on nmemb members of size size — and it checks for integer overflow in the calculation nmemb * size. that's the whole point. that's the moment. 👑

recallocarray() is the one you use for the allocation of memory holding sensitive data, and it guarantees that memory becoming unallocated is explicitly discarded — meaning cached free objects are cleared with explicit_bzero(3). so nothing lingers. no crumbs. 🍓

recallocarray() is similar to reallocarray() except it ensures newly allocated memory is cleared similar to calloc(). and there are two cases, bestie:

• if ptr is NULL, then 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. not "kinda weird", not "maybe fine" — undefined. 💀

freezero() is similar to the free() function except it ensures memory is explicitly discarded. the rules:

• if ptr is NULL, no action occurs. (iconic, zero drama)
• if ptr is not NULL, the size argument must be equal to or smaller than the size of the earlier allocation that returned ptr.

and freezero() guarantees the memory range starting at ptr with length size is discarded while deallocating the whole object originally allocated. so it wipes the part you care about, then frees the whole thing. slay. 🔥

---

🎀 RETURN VALUES 🎀

reallocarray() and recallocarray() return a pointer to the allocated space if successful; otherwise, a null pointer is returned and errno is set to ENOMEM.

if multiplying nmemb and size results in integer overflow, reallocarray() and recallocarray() return NULL and set errno to ENOMEM. caught it. 💅

if ptr is not NULL and multiplying oldnmemb and size results in integer overflow, recallocarray() returns NULL and sets errno to EINVAL. (yes, different errno. read it again. 😭)

---

🌈 IDIOMS 🌈

okay this is the part where the manpage is basically your older sister going "bestie, please, I've seen things." 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 integer overflow:

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

a drop-in replacement is reallocarray():

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

alternatively, calloc() may be used at the cost of initialization overhead. (you pay for the zeroing, basically 🫠)

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 program 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 allocated. 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(). instead 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 containing sensitive data like keys. to avoid leaking information, it guarantees memory is cleared before placing it on the internal free list. deallocation of such an object should be done by calling freezero(). 🔐

---

👀 SEE ALSO 👀

malloc(3), calloc(3), alloca(3)

---

🦋 HISTORY 🦋

the reallocarray() function appeared in OpenBSD 5.6, DragonFly 5.5 and glibc 2.26.

the recallocarray() function appeared in OpenBSD 6.1 and DragonFly 5.5.

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

---

and that's the whole page, bestie 🫶 this one's from Debian, dated September 14, 2019, and it lives at reallocarray(3bsd). now go forth and never write malloc(num * size) again. I'm watching. 💖✨