---
name: "mandoc_malloc"
section: "3"
platform: "linux"
package: "libmandoc-dev"
version: "1.14.6-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mandoc_malloc"
---

# mandoc\_malloc(3)

memory allocation function wrappers used in the mandoc library

## 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

These functions call the libc functions of the same names, passing through their return values when successful. In case of failure, they do not return, but instead call [err(3)](/err/3.md). They can be used both internally by any code in the mandoc libraries and externally by programs using that library, for example [mandoc(1)](/mandoc/1.md), [man(1)](/man/1.md), [apropos(1)](/apropos/1.md), [makewhatis(8)](/makewhatis/8.md), and man.cgi(8).

The function **mandoc\_malloc**() allocates one new object, leaving the memory uninitialized. The functions **mandoc\_realloc**(), **mandoc\_reallocarray**(), and **mandoc\_recallocarray**() change the size of an existing object or array, possibly moving it. When shrinking the size, existing data is truncated; when growing, only **mandoc\_recallocarray**() initializes the new elements to zero. The function **mandoc\_calloc**() allocates a new array, initializing it to zero.

The argument *size* is the size of each object. The argument *nmemb* is the new number of objects in the array. The argument *oldnmemb* is the number of objects in the array before the call. The argument *ptr* is a pointer to the existing object or array to be resized; if it is NULL, a new object or array is allocated.

The functions **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. The function **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.

When the objects and strings are no longer needed, the pointers returned by these functions can be passed to [free(3)](/free/3.md).

## RETURN VALUES

The function **mandoc\_asprintf**() always returns the number of characters written, excluding the final NUL byte. It never returns -1.

The other functions always return a valid pointer; they never return NULL.

## FILES

These functions are implemented in *mandoc\_aux.c*.

## SEE ALSO

[asprintf(3)](/asprintf/3.md), [err(3)](/err/3.md), [malloc(3)](/malloc/3.md), [strdup(3)](/strdup/3.md)

## STANDARDS

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

The function **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.

## HISTORY

The functions **mandoc\_malloc**(), **mandoc\_realloc**(), **mandoc\_calloc**(), and **mandoc\_strdup**() have been available since mandoc 1.9.12, **mandoc\_strndup**() since 1.11.5, **mandoc\_asprintf**() since 1.12.4, **mandoc\_reallocarray**() since 1.13.0, and **mandoc\_recallocarray**() since 1.14.2.

## AUTHORS

Kristaps Dzonsons ⟨*kristaps@bsd.lv*⟩ Ingo Schwarze ⟨*schwarze@openbsd.org*⟩