1.\" $Id: mandoc_malloc.3,v 1.2 2016/07/07 19:19:01 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: July 7 2016 $ 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_strdup , 26.Nm mandoc_strndup , 27.Nm mandoc_asprintf 28.Nd memory allocation function wrappers used in the mandoc library 29.Sh SYNOPSIS 30.In sys/types.h 31.In mandoc_aux.h 32.Ft "void *" 33.Fo mandoc_malloc 34.Fa "size_t size" 35.Fc 36.Ft "void *" 37.Fo mandoc_realloc 38.Fa "void *ptr" 39.Fa "size_t size" 40.Fc 41.Ft "void *" 42.Fo mandoc_reallocarray 43.Fa "void *ptr" 44.Fa "size_t nmemb" 45.Fa "size_t size" 46.Fc 47.Ft "void *" 48.Fo mandoc_calloc 49.Fa "size_t nmemb" 50.Fa "size_t size" 51.Fc 52.Ft "char *" 53.Fo mandoc_strdup 54.Fa "const char *s" 55.Fc 56.Ft "char *" 57.Fo mandoc_strndup 58.Fa "const char *s" 59.Fa "size_t maxlen" 60.Fc 61.Ft int 62.Fo mandoc_asprintf 63.Fa "char **ret" 64.Fa "const char *format" 65.Fa "..." 66.Fc 67.Sh DESCRIPTION 68These functions call the libc functions of the same names, passing 69through their return values when successful. 70In case of failure, they do not return, but instead call 71.Xr err 3 . 72They can be used both internally by any code in the mandoc libraries 73and externally by programs using that library, for example 74.Xr mandoc 1 , 75.Xr man 1 , 76.Xr apropos 1 , 77.Xr makewhatis 8 , 78and 79.Xr man.cgi 8 . 80.Pp 81The function 82.Fn mandoc_malloc 83allocates one new object, leaving the memory uninitialized. 84The functions 85.Fn mandoc_realloc 86and 87.Fn mandoc_reallocarray 88change the size of an existing object or array, possibly moving it. 89When shrinking the size, existing data is truncated; when growing, 90the additional memory is not initialized. 91The function 92.Fn mandoc_calloc 93allocates a new array, initializing it to zero. 94.Pp 95The argument 96.Fa size 97is the size of each object. 98The argument 99.Fa nmemb 100is the new number of objects in the array. 101The argument 102.Fa ptr 103is a pointer to the existing object or array to be resized; if it is 104.Dv NULL , 105a new object or array is allocated. 106.Pp 107The functions 108.Fn mandoc_strdup 109and 110.Fn mandoc_strndup 111copy a string into newly allocated memory. 112For 113.Fn mandoc_strdup , 114the string pointed to by 115.Fa s 116needs to be NUL-terminated. 117For 118.Fn mandoc_strndup , 119at most 120.Fa maxlen 121bytes are copied. 122The function 123.Fn mandoc_asprintf 124writes output formatted according to 125.Fa format 126into newly allocated memory and returns a pointer to the result in 127.Fa ret . 128For all three string functions, the result is always NUL-terminated. 129.Pp 130When the objects and strings are no longer needed, 131the pointers returned by these functions can be passed to 132.Xr free 3 . 133.Sh RETURN VALUES 134The function 135.Fn mandoc_asprintf 136always returns the number of characters written, excluding the 137final NUL byte. 138It never returns -1. 139.Pp 140The other functions always return a valid pointer; they never return 141.Dv NULL . 142.Sh FILES 143These functions are implemented in 144.Pa mandoc_aux.c . 145.Sh SEE ALSO 146.Xr asprintf 3 , 147.Xr err 3 , 148.Xr malloc 3 , 149.Xr strdup 3 150.Sh STANDARDS 151The functions 152.Fn malloc , 153.Fn realloc , 154and 155.Fn calloc 156are required by 157.St -ansiC . 158The functions 159.Fn strdup 160and 161.Fn strndup 162are required by 163.St -p1003.1-2008 . 164The function 165.Fn asprintf 166is a widespread extension that first appeared in the GNU C library. 167.Pp 168The function 169.Fn reallocarray 170is an extension that first appeared in 171.Ox 5.6 . 172If it is not provided by the operating system, the mandoc build system 173uses a bundled portable implementation. 174.Sh HISTORY 175The functions 176.Fn mandoc_malloc , 177.Fn mandoc_realloc , 178.Fn mandoc_calloc , 179and 180.Fn mandoc_strdup 181have been available since mandoc 1.9.12, 182.Fn mandoc_strndup 183since 1.11.5, 184and 185.Fn mandoc_asprintf 186and 187.Fn mandoc_reallocarray 188since 1.12.4 and 1.13.0. 189.Sh AUTHORS 190.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv 191.An Ingo Schwarze Aq Mt schwarze@openbsd.org 192