.\"
.\" Copyright (c) 1980, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" 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.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
.\"
.\"	$OpenBSD: malloc.3,v 1.126 2019/09/14 13:16:50 otto Exp $
.\"
.Dd $Mdocdate: September 14 2019 $
.Dt REALLOCARRAY 3bsd
.Os
.Sh NAME
.Nm reallocarray ,
.Nm recallocarray ,
.Nm freezero
.Nd memory allocation and deallocation
.Sh LIBRARY
.ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
.ds doc-str-Lb-libbsd \*[str-Lb-libbsd]
.Lb libbsd
.Sh SYNOPSIS
.In stdlib.h
(See
.Xr libbsd 7
for include usage.)
.Ft void *
.Fn reallocarray "void *ptr" "size_t nmemb" "size_t size"
.Ft void *
.Fn recallocarray "void *ptr" "size_t oldnmemb" "size_t nmemb" "size_t size"
.Ft void
.Fn freezero "void *ptr" "size_t size"
.Sh DESCRIPTION
.Pp
Designed for safe allocation of arrays,
the
.Fn reallocarray
function is similar to
.Fn realloc
except it operates on
.Fa nmemb
members of size
.Fa size
and checks for integer overflow in the calculation
.Fa nmemb
*
.Fa size .
.Pp
Used for the allocation of memory holding sensitive data,
the
.Fn recallocarray
function guarantees that memory becoming unallocated is explicitly
.Em discarded ,
meaning cached free objects are cleared with
.Xr explicit_bzero 3 .
.Pp
The
.Fn recallocarray
function is similar to
.Fn reallocarray
except it ensures newly allocated memory is cleared similar to
.Fn calloc .
If
.Fa ptr
is
.Dv NULL ,
.Fa oldnmemb
is ignored and the call is equivalent to
.Fn calloc .
If
.Fa ptr
is not
.Dv NULL ,
.Fa oldnmemb
must be a value such that
.Fa oldnmemb
*
.Fa size
is the size of the earlier allocation that returned
.Fa ptr ,
otherwise the behavior is undefined.
The
.Fn freezero
function is similar to the
.Fn free
function except it ensures memory is explicitly discarded.
If
.Fa ptr
is
.Dv NULL ,
no action occurs.
If
.Fa ptr
is not
.Dv NULL ,
the
.Fa size
argument must be equal to or smaller than the size of the earlier allocation
that returned
.Fa ptr .
.Fn freezero
guarantees the memory range starting at
.Fa ptr
with length
.Fa size
is discarded while deallocating the whole object originally allocated.
.Sh RETURN VALUES
The
.Fn reallocarray
and
.Fn recallocarray
functions return a pointer to the allocated space if successful; otherwise,
a null pointer is returned and
.Va errno
is set to
.Er ENOMEM .
.Pp
If multiplying
.Fa nmemb
and
.Fa size
results in integer overflow,
.Fn reallocarray
and
.Fn recallocarray
return
.Dv NULL
and set
.Va errno
to
.Er ENOMEM .
.Pp
If
.Fa ptr
is not
.Dv NULL
and multiplying
.Fa oldnmemb
and
.Fa size
results in integer overflow
.Fn recallocarray
returns
.Dv NULL
and sets
.Va errno
to
.Er EINVAL .
.Sh IDIOMS
Consider
.Fn calloc
or the extensions
.Fn reallocarray
and
.Fn recallocarray
when there is multiplication in the
.Fa size
argument of
.Fn malloc
or
.Fn realloc .
For example, avoid this common idiom as it may lead to integer overflow:
.Bd -literal -offset indent
if ((p = malloc(num * size)) == NULL)
	err(1, NULL);
.Ed
.Pp
A drop-in replacement is
.Fn reallocarray :
.Bd -literal -offset indent
if ((p = reallocarray(NULL, num, size)) == NULL)
	err(1, NULL);
.Ed
.Pp
Alternatively,
.Fn calloc
may be used at the cost of initialization overhead.
.Pp
When using
.Fn realloc ,
be careful to avoid the following idiom:
.Bd -literal -offset indent
size += 50;
if ((p = realloc(p, size)) == NULL)
	return (NULL);
.Ed
.Pp
Do not adjust the variable describing how much memory has been allocated
until the allocation has been successful.
This can cause aberrant program behavior if the incorrect size value is used.
In most cases, the above sample will also result in a leak of memory.
As stated earlier, a return value of
.Dv NULL
indicates that the old object still remains allocated.
Better code looks like this:
.Bd -literal -offset indent
newsize = size + 50;
if ((newp = realloc(p, newsize)) == NULL) {
	free(p);
	p = NULL;
	size = 0;
	return (NULL);
}
p = newp;
size = newsize;
.Ed
.Pp
As with
.Fn malloc ,
it is important to ensure the new size value will not overflow;
i.e. avoid allocations like the following:
.Bd -literal -offset indent
if ((newp = realloc(p, num * size)) == NULL) {
	...
.Ed
.Pp
Instead, use
.Fn reallocarray :
.Bd -literal -offset indent
if ((newp = reallocarray(p, num, size)) == NULL) {
	...
.Ed
.Pp
Calling
.Fn realloc
with a
.Dv NULL
.Fa ptr
is equivalent to calling
.Fn malloc .
Instead of this idiom:
.Bd -literal -offset indent
if (p == NULL)
	newp = malloc(newsize);
else
	newp = realloc(p, newsize);
.Ed
.Pp
Use the following:
.Bd -literal -offset indent
newp = realloc(p, newsize);
.Ed
.Pp
The
.Fn recallocarray
function should be used for resizing objects containing sensitive data like
keys.
To avoid leaking information,
it guarantees memory is cleared before placing it on the internal free list.
Deallocation of such an object should be done by calling
.Fn freezero .
.Sh SEE ALSO
.Xr malloc 3 ,
.Xr calloc 3 ,
.Xr alloca 3
.Sh HISTORY
The
.Fn reallocarray
function appeared in
.Ox 5.6 ,
and glibc 2.26.
The
.Fn recallocarray
function appeared in
.Ox 6.1 .
The
.Fn freezero
function appeared in
.Ox 6.2 .