.TH "MANDOC_MALLOC" "3" "$Mdocdate: August 5 2014 $" "Debian" "Library Functions Manual"
.nh
.if n .ad l
.SH "NAME"
\fBmandoc_malloc\fR,
\fBmandoc_realloc\fR,
\fBmandoc_reallocarray\fR,
\fBmandoc_calloc\fR,
\fBmandoc_strdup\fR,
\fBmandoc_strndup\fR,
\fBmandoc_asprintf\fR
\- memory allocation function wrappers used in the mandoc library
.SH "LIBRARY"
Mandoc Macro Compiler Library (libmandoc, \-lmandoc)
.SH "SYNOPSIS"
\fB#include <sys/types.h>\fR
.br
\fB#include <mandoc_aux.h>\fR
.sp
\fIvoid *\fR
.PD 0
.HP 4n
\fBmandoc_malloc\fR(\fIsize_t\ size\fR);
.PD
.PP
\fIvoid *\fR
.PD 0
.HP 4n
\fBmandoc_realloc\fR(\fIvoid\ *ptr\fR,
\fIsize_t\ size\fR);
.PD
.PP
\fIvoid *\fR
.PD 0
.HP 4n
\fBmandoc_reallocarray\fR(\fIvoid\ *ptr\fR,
\fIsize_t\ nmemb\fR,
\fIsize_t\ size\fR);
.PD
.PP
\fIvoid *\fR
.PD 0
.HP 4n
\fBmandoc_calloc\fR(\fIsize_t\ nmemb\fR,
\fIsize_t\ size\fR);
.PD
.PP
\fIchar *\fR
.PD 0
.HP 4n
\fBmandoc_strdup\fR(\fIconst\ char\ *s\fR);
.PD
.PP
\fIchar *\fR
.PD 0
.HP 4n
\fBmandoc_strndup\fR(\fIconst\ char\ *s\fR,
\fIsize_t\ maxlen\fR);
.PD
.PP
\fIint\fR
.PD 0
.HP 4n
\fBmandoc_asprintf\fR(\fIchar\ **ret\fR,
\fIconst\ char\ *format\fR,
\fI...\fR);
.PD
.SH "DESCRIPTION"
These functions call the
Standard C Library (libc, \-lc)
functions of the same names, passing through their return values when
successful.
In case of failure, they do not return, but instead call
perror(3)
and
exit(3).
They can be used both internally by any code in the
Mandoc Macro Compiler Library (libmandoc, \-lmandoc)
and externally by programs using that library, for example
mandoc(1),
apropos(1),
and
makewhatis(8).
.PP
The function
\fBmandoc_malloc\fR()
allocates one new object, leaving the memory uninitialized.
The functions
\fBmandoc_realloc\fR()
and
\fBmandoc_reallocarray\fR()
change the size of an existing object or array, possibly moving it.
When shrinking the size, existing data is truncated; when growing,
the additional memory is not initialized.
The function
\fBmandoc_calloc\fR()
allocates a new array, initializing it to zero.
.PP
The argument
\fIsize\fR
is the size of each object.
The argument
\fInmemb\fR
is the new number of objects in the array.
The argument
\fIptr\fR
is a pointer to the existing object or array to be resized; if it is
\fRNULL\fR,
a new object or array is allocated.
.PP
The functions
\fBmandoc_strdup\fR()
and
\fBmandoc_strndup\fR()
copy a string into newly allocated memory.
For
\fBmandoc_strdup\fR(),
the string pointed to by
\fIs\fR
needs to be NUL-terminated.
For
\fBmandoc_strndup\fR(),
at most
\fImaxlen\fR
bytes are copied.
The function
\fBmandoc_asprintf\fR()
writes output formatted according to
\fIformat\fR
into newly allocated memory and returns a pointer to the result in
\fIret\fR.
For all three string functions, the result is always NUL-terminated.
.PP
When the objects and strings are no longer needed,
the pointers returned by these functions can be passed to
free(3).
.SH "RETURN VALUES"
The function
\fBmandoc_asprintf\fR()
always returns the number of characters written, excluding the
final NUL byte.
It never returns -1.
.PP
The other functions always return a valid pointer; they never return
\fRNULL\fR.
.SH "FILES"
These functions are implemented in
\fImandoc_aux.c\fR.
.SH "SEE ALSO"
asprintf(3),
exit(3),
malloc(3),
perror(3),
strdup(3)
.SH "STANDARDS"
The functions
\fBmalloc\fR(),
\fBrealloc\fR(),
and
\fBcalloc\fR()
are required by
ANSI X3.159-1989 (\(LqANSI\~C89\(Rq).
The functions
\fBstrdup\fR()
and
\fBstrndup\fR()
are required by
IEEE Std 1003.1-2008 (\(LqPOSIX.1\(Rq).
The function
\fBasprintf\fR()
is a widespread extension that first appeared in the GNU C library.
.PP
The function
\fBreallocarray\fR()
is an extension that first appeared in
OpenBSD\ 5.6.
If it is not provided by the operating system, the mandoc build system
uses a bundled portable implementation.
.SH "HISTORY"
The functions
\fBmandoc_malloc\fR(),
\fBmandoc_realloc\fR(),
\fBmandoc_calloc\fR(),
and
\fBmandoc_strdup\fR()
have been available since mandoc 1.9.12,
\fBmandoc_strndup\fR()
since 1.11.5,
and
\fBmandoc_asprintf\fR()
and
\fBmandoc_reallocarray\fR()
since 1.12.4 and 1.13.0.
.SH "AUTHORS"
Kristaps Dzonsons <\fIkristaps@bsd.lv\fR>
.br
Ingo Schwarze <\fIschwarze@openbsd.org\fR>