1.\" $Id: mandoc_malloc.3,v 1.3 2021/09/17 18:50:21 schwarze Exp $ 2.\" 3.\" Copyright (c) 2014 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 17 2021 $ 18.Dt MANDOC_MALLOC 3 19.Os 20.Sh NAME 21.Nm mandoc_malloc , 22.Nm mandoc_realloc , 23.Nm mandoc_reallocarray , 24.Nm mandoc_calloc , 25.Nm mandoc_recallocarray , 26.Nm mandoc_strdup , 27.Nm mandoc_strndup , 28.Nm mandoc_asprintf 29.Nd memory allocation function wrappers used in the mandoc library 30.Sh SYNOPSIS 31.In sys/types.h 32.In mandoc_aux.h 33.Ft "void *" 34.Fo mandoc_malloc 35.Fa "size_t size" 36.Fc 37.Ft "void *" 38.Fo mandoc_realloc 39.Fa "void *ptr" 40.Fa "size_t size" 41.Fc 42.Ft "void *" 43.Fo mandoc_reallocarray 44.Fa "void *ptr" 45.Fa "size_t nmemb" 46.Fa "size_t size" 47.Fc 48.Ft "void *" 49.Fo mandoc_calloc 50.Fa "size_t nmemb" 51.Fa "size_t size" 52.Fc 53.Ft "void *" 54.Fo mandoc_recallocarray 55.Fa "void *ptr" 56.Fa "size_t oldnmemb" 57.Fa "size_t nmemb" 58.Fa "size_t size" 59.Fc 60.Ft "char *" 61.Fo mandoc_strdup 62.Fa "const char *s" 63.Fc 64.Ft "char *" 65.Fo mandoc_strndup 66.Fa "const char *s" 67.Fa "size_t maxlen" 68.Fc 69.Ft int 70.Fo mandoc_asprintf 71.Fa "char **ret" 72.Fa "const char *format" 73.Fa "..." 74.Fc 75.Sh DESCRIPTION 76These functions call the libc functions of the same names, passing 77through their return values when successful. 78In case of failure, they do not return, but instead call 79.Xr err 3 . 80They can be used both internally by any code in the mandoc libraries 81and externally by programs using that library, for example 82.Xr mandoc 1 , 83.Xr man 1 , 84.Xr apropos 1 , 85.Xr makewhatis 8 , 86and 87.Xr man.cgi 8 . 88.Pp 89The function 90.Fn mandoc_malloc 91allocates one new object, leaving the memory uninitialized. 92The functions 93.Fn mandoc_realloc , 94.Fn mandoc_reallocarray , 95and 96.Fn mandoc_recallocarray 97change the size of an existing object or array, possibly moving it. 98When shrinking the size, existing data is truncated; when growing, 99only 100.Fn mandoc_recallocarray 101initializes the new elements to zero. 102The function 103.Fn mandoc_calloc 104allocates a new array, initializing it to zero. 105.Pp 106The argument 107.Fa size 108is the size of each object. 109The argument 110.Fa nmemb 111is the new number of objects in the array. 112The argument 113.Fa oldnmemb 114is the number of objects in the array before the call. 115The argument 116.Fa ptr 117is a pointer to the existing object or array to be resized; if it is 118.Dv NULL , 119a new object or array is allocated. 120.Pp 121The functions 122.Fn mandoc_strdup 123and 124.Fn mandoc_strndup 125copy a string into newly allocated memory. 126For 127.Fn mandoc_strdup , 128the string pointed to by 129.Fa s 130needs to be NUL-terminated. 131For 132.Fn mandoc_strndup , 133at most 134.Fa maxlen 135bytes are copied. 136The function 137.Fn mandoc_asprintf 138writes output formatted according to 139.Fa format 140into newly allocated memory and returns a pointer to the result in 141.Fa ret . 142For all three string functions, the result is always NUL-terminated. 143.Pp 144When the objects and strings are no longer needed, 145the pointers returned by these functions can be passed to 146.Xr free 3 . 147.Sh RETURN VALUES 148The function 149.Fn mandoc_asprintf 150always returns the number of characters written, excluding the 151final NUL byte. 152It never returns -1. 153.Pp 154The other functions always return a valid pointer; they never return 155.Dv NULL . 156.Sh FILES 157These functions are implemented in 158.Pa mandoc_aux.c . 159.Sh SEE ALSO 160.Xr asprintf 3 , 161.Xr err 3 , 162.Xr malloc 3 , 163.Xr strdup 3 164.Sh STANDARDS 165The functions 166.Fn malloc , 167.Fn realloc , 168and 169.Fn calloc 170are required by 171.St -ansiC . 172The functions 173.Fn strdup 174and 175.Fn strndup 176are required by 177.St -p1003.1-2008 . 178The function 179.Fn asprintf 180is a widespread extension that first appeared in the GNU C library. 181.Pp 182The function 183.Fn reallocarray 184is an extension that first appeared in 185.Ox 5.6 , 186and 187.Fn recallocarray 188in 189.Ox 6.1 . 190If these two are not provided by the operating system, 191the mandoc build system uses bundled portable implementations. 192.Sh HISTORY 193The functions 194.Fn mandoc_malloc , 195.Fn mandoc_realloc , 196.Fn mandoc_calloc , 197and 198.Fn mandoc_strdup 199have been available since mandoc 1.9.12, 200.Fn mandoc_strndup 201since 1.11.5, 202.Fn mandoc_asprintf 203since 1.12.4, 204.Fn mandoc_reallocarray 205since 1.13.0, and 206.Fn mandoc_recallocarray 207since 1.14.2. 208.Sh AUTHORS 209.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 210.An Ingo Schwarze Aq Mt schwarze@openbsd.org 211