\" $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.
