1MANDOC_MALLOC(3) BSD Library Functions Manual MANDOC_MALLOC(3)
2
4 mandoc_malloc, mandoc_realloc, mandoc_reallocarray, mandoc_calloc,
5 mandoc_recallocarray, mandoc_strdup, mandoc_strndup, mandoc_asprintf —
6 memory allocation function wrappers used in the mandoc library
7
9 #include <sys/types.h>
10 #include <mandoc_aux.h>
11 void *
13 mandoc_malloc(size_t size);
14 void *
16 mandoc_realloc(void *ptr, size_t size);
17 void *
19 mandoc_reallocarray(void *ptr, size_t nmemb, size_t size);
20 void *
22 mandoc_calloc(size_t nmemb, size_t size);
23 void *
25 mandoc_recallocarray(void *ptr, size_t oldnmemb, size_t nmemb,
26 size_t size);
27 char *
29 mandoc_strdup(const char *s);
30 char *
32 mandoc_strndup(const char *s, size_t maxlen);
33 int
35 mandoc_asprintf(char **ret, const char *format, ...);
36
38 These functions call the libc functions of the same names, passing
39 through their return values when successful. In case of failure, they do
40 not return, but instead call err(3). They can be used both internally by
41 any code in the mandoc libraries and externally by programs using that
42 library, for example mandoc(1), man(1), apropos(1), makewhatis(8), and
43 man.cgi(8).
44 The function mandoc_malloc() allocates one new object, leaving the memory
46 uninitialized. The functions mandoc_realloc(), mandoc_reallocarray(),
47 and mandoc_recallocarray() change the size of an existing object or ar‐
48 ray, possibly moving it. When shrinking the size, existing data is trun‐
49 cated; when growing, only mandoc_recallocarray() initializes the new ele‐
50 ments to zero. The function mandoc_calloc() allocates a new array, ini‐
51 tializing it to zero.
52 The argument size is the size of each object. The argument nmemb is the
54 new number of objects in the array. The argument oldnmemb is the number
55 of objects in the array before the call. The argument ptr is a pointer
56 to the existing object or array to be resized; if it is NULL, a new ob‐
57 ject or array is allocated.
58 The functions mandoc_strdup() and mandoc_strndup() copy a string into
60 newly allocated memory. For mandoc_strdup(), the string pointed to by s
61 needs to be NUL-terminated. For mandoc_strndup(), at most maxlen bytes
62 are copied. The function mandoc_asprintf() writes output formatted ac‐
63 cording to format into newly allocated memory and returns a pointer to
64 the result in ret. For all three string functions, the result is always
65 NUL-terminated.
66 When the objects and strings are no longer needed, the pointers returned
68 by these functions can be passed to free(3).
69
71 The function mandoc_asprintf() always returns the number of characters
72 written, excluding the final NUL byte. It never returns -1.
73 The other functions always return a valid pointer; they never return
75 NULL.
76
78 These functions are implemented in mandoc_aux.c.
79
81 asprintf(3), err(3), malloc(3), strdup(3)
82
84 The functions malloc(), realloc(), and calloc() are required by ANSI
85 X3.159-1989 (“ANSI C89”). The functions strdup() and strndup() are re‐
86 quired by IEEE Std 1003.1-2008 (“POSIX.1”). The function asprintf() is a
87 widespread extension that first appeared in the GNU C library.
88 The function reallocarray() is an extension that first appeared in
90 OpenBSD 5.6, and recallocarray() in OpenBSD 6.1. If these two are not
91 provided by the operating system, the mandoc build system uses bundled
92 portable implementations.
93
95 The functions mandoc_malloc(), mandoc_realloc(), mandoc_calloc(), and
96 mandoc_strdup() have been available since mandoc 1.9.12, mandoc_strndup()
97 since 1.11.5, mandoc_asprintf() since 1.12.4, mandoc_reallocarray() since
98 1.13.0, and mandoc_recallocarray() since 1.14.2.
99
101 Kristaps Dzonsons <kristaps@bsd.lv>
102 Ingo Schwarze <schwarze@openbsd.org>
103BSD September 17, 2021 BSD