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

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), err(3), malloc(3), strdup(3)

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>

Debian                                         September 17, 2021                               MANDOC_MALLOC(3)