1.\" $NetBSD: reallocarr.3,v 1.7 2022/08/31 12:18:41 riastradh Exp $ 2.\" 3.\" Copyright (c) 2015 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 20.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 21.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 25.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 26.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 27.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.Dd August 31, 2022 30.Dt REALLOCARR 3 31.Os 32.Sh NAME 33.Nm reallocarr 34.Nd reallocate array 35.Sh SYNOPSIS 36.In stdlib.h 37.Ft int 38.Fo reallocarr 39.Fa "void *ptrp" 40.Fa "size_t number" 41.Fa "size_t size" 42.Fc 43.Sh DESCRIPTION 44The 45.Nm 46function safely allocates, resizes, or frees arrays in memory. 47.Pp 48If 49.Fa ptr 50is a null pointer, or a pointer to memory previously allocated with 51.Nm , 52then 53.Fo reallocarr 54.Li & Ns Fa ptr , 55.Fa number , 56.Fa size 57.Fc 58allocates or reallocates the memory that 59.Fa ptr 60points to, possibly moving it to a different location in memory, so 61that it has space for an array of 62.Fa number 63elements of 64.Fa size 65bytes apiece. 66.Nm 67updates 68.Fa ptr 69in case it was moved on success, and leaves it unchanged on failure. 70.Pp 71If 72.Fa ptr 73was previously allocated, the objects stored at 74.Fa ptr Ns Li "[0]" , 75.Fa ptr Ns Li "[1]" , 76\&..., 77up to the shorter of its old 78.Fa number 79and its new 80.Fa number , 81are copied into the new memory, like 82.Xr realloc 3 . 83.Pp 84.Fa ptr 85may be null and 86.Fa number 87may be zero. 88.Fa size 89must be nonzero. 90.Pp 91The memory allocated by 92.Nm 93may be freed with 94.Fo reallocarr 95.Li & Ns Fa ptr , 96.Li 0 , 97.Fa size 98.Fc , 99which will always succeed and unconditionally set 100.Fa ptr 101to null. 102.Pp 103Like 104.Xr calloc 3 , 105.Nm 106fails gracefully if the product of 107.Fa number 108and 109.Fa size 110would overflow the representable size of memory. 111Unlike 112.Xr calloc 3 , 113new memory allocated by 114.Nm 115is not zero-initialized. 116.Pp 117The 118.Nm 119function may alter 120.Va errno 121as a side effect. 122.Pp 123Note that the argument 124.Fa ptrp 125is a pointer to a pointer to allocated memory, unlike 126.Xr realloc 3 127which takes a pointer to allocated memory. 128.Sh RETURN VALUES 129On successful completion, 130.Nm 131returns 0 and updates 132.Fa ptr . 133Otherwise, an 134.Xr errno 2 135is returned, and 136.Fa ptr 137and the memory it points to are unmodified. 138.Sh EXAMPLES 139The following uses 140.Fn reallocarr 141to initialize an array of 142.Dv INITSIZE 143integers, then 144resizes it to 145.Dv NEWSIZE 146elements, and finally frees it: 147.Bd -literal -offset indent 148int *data = NULL; 149int error = 0; 150 151/* allocate */ 152error = reallocarr(&data, INITSIZE, sizeof(*data)); 153if (error) 154 errc(1, error, "reallocarr failed"); 155\&... 156/* resize */ 157error = reallocarr(&data, NEWSIZE, sizeof(*data)); 158if (error) 159 errc(1, error, "reallocarr failed on resize"); 160\&... 161/* free */ 162(void)reallocarr(&data, 0, sizeof(*data)); 163assert(data == NULL); 164.Ed 165.Sh SEE ALSO 166.Xr calloc 3 , 167.Xr realloc 3 , 168.Xr reallocarray 3 169.Sh HISTORY 170.Nm 171first appeared in 172.Nx 7.0 . 173.Ox 174introduced the 175.Xr reallocarray 3 176function for the same purpose, but the interface makes it difficult 177to correctly handle zero-sized allocations. 178