Home | History | Annotate | Line # | Download | only in stdlib
reallocarray.3 revision 1.3 
 $NetBSD: reallocarray.3,v 1.3 2015/02/06 08:37:39 wiz Exp $

.Dd February 5, 2015
.Dt REALLOCARRAY 3
.Os
.Sh NAME
.Nm reallocarray
.Nd reallocate memory for an array of elements checking for overflow
.Sh SYNOPSIS
.Vt #define _OPENBSD_SOURCE
n stdlib.h .Ft void *
.Fo reallocarray
.Fa "void *ptr"
.Fa "size_t nmemb"
.Fa "size_t size"
.Fc
.Sh DESCRIPTION
The
.Fn reallocarray
function reallocates the pointer
.Fa ptr
to a size appropriate to handle an allocation of
.Fa nmemb
elements in an array where each of the array elements is
.Fa size
bytes using
.Xr realloc 3
and making sure that overflow does not happen in the multiplication of
.Dq "nmemb * size" .

p
This function is provided for source compatibility with
.Ox
and
its use is discouraged in preference to
.Xr reallocarr 3 .
.Sh RETURN VALUES
The
.Fn reallocarray
function will return
.Dv NULL
if there was overflow or if
.Xr realloc 3
failed setting
.Va errno
to
.Dv EOVERFLOW
or preserving the value from
.Xr realloc 3 .
.Sh SEE ALSO
.Xr malloc 3 ,
.Xr realloc 3 ,
.Xr reallocarr 3
.Sh STANDARDS
.Fn reallocarray
is an
.Ox
extension.
.Sh HISTORY
The
.Fn reallocarray
function first appeared in
.Ox 5.6 .
.Fn reallocarray
was redesigned in
.Nx 8
as
.Fn reallocarr 3 .
For compatibility reasons it's available since
.Nx 8
in the
.Vt _OPENBSD_SOURCE
namespace.
.Sh CAVEATS
The
.Fn reallocarray
function was designed to facilitate safe,
robust programming and overcome the shortcomings of the
.Xr malloc 3
and
.Xr realloc 3
functions by centralizing the overflow check in the multiplication of
.Fa nmemb
and
.Fa size .

p
There are still portability issues (it does not solve
the
.Dv 0
sized allocation return ambiguity in the C standard: does
.Fn reallocarray
return
.Dv NULL
or a unique pointer to memory that cannot be accessed? Does a
.Dv NULL
mean that an error occurred, and can someone check
.Dv errno
in that case to find out what happened?).

p
For this reason
.Nx
decided to go with an alternative implementation, and created
.Xr reallocarr 3 .