1MANDOC_MALLOC(3) BSD Library Functions Manual MANDOC_MALLOC(3)
2
4 mandoc_malloc, mandoc_realloc, mandoc_reallocarray, mandoc_calloc,
5 mandoc_strdup, mandoc_strndup, mandoc_asprintf — memory allocation func‐
6 tion 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 char *
25 mandoc_strdup(const char *s);
26 char *
28 mandoc_strndup(const char *s, size_t maxlen);
29 int
31 mandoc_asprintf(char **ret, const char *format, ...);
32
34 These functions call the libc functions of the same names, passing
35 through their return values when successful. In case of failure, they do
36 not return, but instead call err(3). They can be used both internally by
37 any code in the mandoc libraries and externally by programs using that
38 library, for example mandoc(1), man(1), apropos(1), makewhatis(8), and
39 man.cgi(8).
40 The function mandoc_malloc() allocates one new object, leaving the memory
42 uninitialized. The functions mandoc_realloc() and mandoc_reallocarray()
43 change the size of an existing object or array, possibly moving it. When
44 shrinking the size, existing data is truncated; when growing, the addi‐
45 tional memory is not initialized. The function mandoc_calloc() allocates
46 a new array, initializing it to zero.
47 The argument size is the size of each object. The argument nmemb is the
49 new number of objects in the array. The argument ptr is a pointer to the
50 existing object or array to be resized; if it is NULL, a new object or
51 array is allocated.
52 The functions mandoc_strdup() and mandoc_strndup() copy a string into
54 newly allocated memory. For mandoc_strdup(), the string pointed to by s
55 needs to be NUL-terminated. For mandoc_strndup(), at most maxlen bytes
56 are copied. The function mandoc_asprintf() writes output formatted
57 according to format into newly allocated memory and returns a pointer to
58 the result in ret. For all three string functions, the result is always
59 NUL-terminated.
60 When the objects and strings are no longer needed, the pointers returned
62 by these functions can be passed to free(3).
63
65 The function mandoc_asprintf() always returns the number of characters
66 written, excluding the final NUL byte. It never returns -1.
67 The other functions always return a valid pointer; they never return
69 NULL.
70
72 These functions are implemented in mandoc_aux.c.
73
75 asprintf(3), err(3), malloc(3), strdup(3)
76
78 The functions malloc(), realloc(), and calloc() are required by ANSI
79 X3.159-1989 (“ANSI C89”). The functions strdup() and strndup() are
80 required by IEEE Std 1003.1-2008 (“POSIX.1”). The function asprintf() is
81 a widespread extension that first appeared in the GNU C library.
82 The function reallocarray() is an extension that first appeared in
84 OpenBSD 5.6. If it is not provided by the operating system, the mandoc
85 build system uses a bundled portable implementation.
86
88 The functions mandoc_malloc(), mandoc_realloc(), mandoc_calloc(), and
89 mandoc_strdup() have been available since mandoc 1.9.12, mandoc_strndup()
90 since 1.11.5, and mandoc_asprintf() and mandoc_reallocarray() since
91 1.12.4 and 1.13.0.
92
94 Kristaps Dzonsons <kristaps@bsd.lv>
95 Ingo Schwarze <schwarze@openbsd.org>
96BSD June 20, 2019 BSD