| MANDOC_MALLOC(3) | Library Functions Manual | MANDOC_MALLOC(3) |
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
#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, ...);
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). 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).
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).
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.
These functions are implemented in mandoc_aux.c.
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.
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.
Kristaps Dzonsons
<kristaps@bsd.lv>
Ingo Schwarze
<schwarze@openbsd.org>
| September 17, 2021 | OpenBSD 6.7 |