.\"	$NetBSD: reallocarr.3,v 1.7 2022/08/31 12:18:41 riastradh Exp $
.\"
.\" Copyright (c) 2015 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.Dd August 31, 2022
.Dt REALLOCARR 3
.Os
.Sh NAME
.Nm reallocarr
.Nd reallocate array
.Sh SYNOPSIS
.In stdlib.h
.Ft int
.Fo reallocarr
.Fa "void *ptrp"
.Fa "size_t number"
.Fa "size_t size"
.Fc
.Sh DESCRIPTION
The
.Nm
function safely allocates, resizes, or frees arrays in memory.
.Pp
If
.Fa ptr
is a null pointer, or a pointer to memory previously allocated with
.Nm ,
then
.Fo reallocarr
.Li & Ns Fa ptr ,
.Fa number ,
.Fa size
.Fc
allocates or reallocates the memory that
.Fa ptr
points to, possibly moving it to a different location in memory, so
that it has space for an array of
.Fa number
elements of
.Fa size
bytes apiece.
.Nm
updates
.Fa ptr
in case it was moved on success, and leaves it unchanged on failure.
.Pp
If
.Fa ptr
was previously allocated, the objects stored at
.Fa ptr Ns Li "[0]" ,
.Fa ptr Ns Li "[1]" ,
\&...,
up to the shorter of its old
.Fa number
and its new
.Fa number ,
are copied into the new memory, like
.Xr realloc 3 .
.Pp
.Fa ptr
may be null and
.Fa number
may be zero.
.Fa size
must be nonzero.
.Pp
The memory allocated by
.Nm
may be freed with
.Fo reallocarr
.Li & Ns Fa ptr ,
.Li 0 ,
.Fa size
.Fc ,
which will always succeed and unconditionally set
.Fa ptr
to null.
.Pp
Like
.Xr calloc 3 ,
.Nm
fails gracefully if the product of
.Fa number
and
.Fa size
would overflow the representable size of memory.
Unlike
.Xr calloc 3 ,
new memory allocated by
.Nm
is not zero-initialized.
.Pp
The
.Nm
function may alter
.Va errno
as a side effect.
.Pp
Note that the argument
.Fa ptrp
is a pointer to a pointer to allocated memory, unlike
.Xr realloc 3
which takes a pointer to allocated memory.
.Sh RETURN VALUES
On successful completion,
.Nm
returns 0 and updates
.Fa ptr .
Otherwise, an
.Xr errno 2
is returned, and
.Fa ptr
and the memory it points to are unmodified.
.Sh EXAMPLES
The following uses
.Fn reallocarr
to initialize an array of
.Dv INITSIZE
integers, then
resizes it to
.Dv NEWSIZE
elements, and finally frees it:
.Bd -literal -offset indent
int *data = NULL;
int error = 0;

/* allocate */
error = reallocarr(&data, INITSIZE, sizeof(*data));
if (error)
	errc(1, error, "reallocarr failed");
\&...
/* resize */
error = reallocarr(&data, NEWSIZE, sizeof(*data));
if (error)
	errc(1, error, "reallocarr failed on resize");
\&...
/* free */
(void)reallocarr(&data, 0, sizeof(*data));
assert(data == NULL);
.Ed
.Sh SEE ALSO
.Xr calloc 3 ,
.Xr realloc 3 ,
.Xr reallocarray 3
.Sh HISTORY
.Nm
first appeared in
.Nx 7.0 .
.Ox
introduced the
.Xr reallocarray 3
function for the same purpose, but the interface makes it difficult
to correctly handle zero-sized allocations.