MANDOC_MALLOC(3)

💖 MANDOC_MALLOC — Library Functions Manual 💖

okay bestie, sit down, hydrate, and let me tell you about the mandoc memory wrappers 💅 these live in the Library Functions Manual section 3, and they are genuinely the most drama-free way to allocate memory that exists. no cap.

---

✨ NAME ✨

mandoc_malloc, mandoc_realloc, mandoc_reallocarray, mandoc_calloc, mandoc_recallocarray, mandoc_strdup, mandoc_strndup, mandoc_asprintf — memory allocation function wrappers used in the mandoc library 🫶

---

🌸 SYNOPSIS 🌸

#include <sys/types.h>
#include <mandoc_aux.h>

void *
mandoc_malloc(size_t size);

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

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

void *
mandoc_calloc(size_t nmemb, size_t size);

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

char *
mandoc_strdup(const char *s);

char *
mandoc_strndup(const char *s, size_t maxlen);

int
mandoc_asprintf(char **ret, const char *format, ...);

---

💜 DESCRIPTION 💜

so here's the tea 🍓 these functions call the libc functions of the same names, and they pass through the return values when everything's successful. but when it fails? they do not return. they call err(3) instead. like, they simply refuse to hand you a broken pointer. iconic behavior honestly 👑

they can be used both internally by any code in the mandoc libraries and externally by programs using that library — for example mandoc(1), man(1), apropos(1), makewhatis(8), and man.cgi(8). so yes, they're for everyone, we share 💖

• mandoc_malloc() — allocates one new object, and leaves the memory uninitialized. it does not clean up after itself, that's on you bestie.
• mandoc_realloc(), mandoc_reallocarray(), and mandoc_recallocarray() — change the size of an existing object or array, and they might move it somewhere else entirely (main character relocation energy). when you're shrinking the size, existing data gets truncated ✂️; when you're growing, only mandoc_recallocarray() initializes the new elements to zero. the others? they leave that new space just... vibing. uninitialized.
• mandoc_calloc() — allocates a new array and initializes it to zero. so clean, so fresh ✨

now the arguments, one by one:

• size — the size of each object.
• nmemb — the new number of objects in the array.
• oldnmemb — the number of objects in the array before the call.
• ptr — a pointer to the existing object or array to be resized. and if it's NULL? a whole new object or array gets allocated 🦋

the string girlies:

• mandoc_strdup() and mandoc_strndup() copy a string into newly allocated memory. for mandoc_strdup(), the string pointed to by s needs to be NUL-terminated. for mandoc_strndup(), at most maxlen bytes are copied.
• mandoc_asprintf() writes output formatted according to format into newly allocated memory and returns a pointer to the result in ret.

for all three string functions, the result is always NUL-terminated. always. periodt.

and when the objects and strings are no longer needed, the pointers returned by these functions can be passed to free(3) 🎀

---

⭐ RETURN VALUES ⭐

• mandoc_asprintf() — always returns the number of characters written, excluding the final NUL byte. it never returns -1. never ever. not once.
• the other functions — always return a valid pointer. they never return NULL. that's just not a thing they do 💅

---

🎀 FILES 🎀

these functions are implemented in mandoc_aux.c.

---

🌈 SEE ALSO 🌈

asprintf(3), err(3), malloc(3), strdup(3)

---

👑 STANDARDS 👑

• malloc(), realloc(), and calloc() are required by ANSI X3.159-1989 (“ANSI C89”).
• strdup() and strndup() are required by IEEE Std 1003.1-2008 (“POSIX.1”).
• asprintf() is a widespread extension that first appeared in the GNU C library.

and now the portable ones, pay attention bestie:

• reallocarray() is an extension that first appeared in OpenBSD 5.6, and recallocarray() in OpenBSD 6.1. if these two are not provided by the operating system, the mandoc build system uses bundled portable implementations. so you're covered either way 🫶

---

🦋 HISTORY 🦋

the timeline, in order, no skips:

1. mandoc_malloc(), mandoc_realloc(), mandoc_calloc(), and mandoc_strdup() — available since mandoc 1.9.12
2. mandoc_strndup() — since 1.11.5
3. mandoc_asprintf() — since 1.12.4
4. mandoc_reallocarray() — since 1.13.0
5. mandoc_recallocarray() — since 1.14.2

they've been growing up so fast 😭

---

💖 AUTHORS 💖

• Kristaps Dzonsons <kristaps@bsd.lv>
• Ingo Schwarze <schwarze@openbsd.org>

---

and that's the whole page, bestie 🧚 this one came from Debian, dated September 17, 2021, living in section MANDOC_MALLOC(3). go forth and never check a malloc return value again — that's literally the whole point 💅✨