plucky (3) mandoc_malloc.3.gz

Provided by: libmandoc-dev_1.14.6-3_amd64 bug

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>