xref: /netbsd-src/lib/libc/stdlib/reallocarray.3 (revision 49e10846a684d8faa456046705ad6d3d7bce8f4c)

.\" $NetBSD: reallocarray.3,v 1.7 2022/12/04 11:25:08 uwe 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 September 9, 2022
.Dt REALLOCARRAY 3
.Os
.Sh NAME
.Nm reallocarray
.Nd reallocate memory for an array of elements checking for overflow
.Sh SYNOPSIS
.In 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" .
Otherwise it behaves like
.Xr realloc 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
.Er ENOMEM
or preserving the value from
.Xr realloc 3 .
.Sh SEE ALSO
.Xr malloc 3 ,
.Xr realloc 3 ,
.Xr reallocarr 3
.\" .Sh STANDARDS
.\" Will be part of POSIX, but isn't yet.
.Sh HISTORY
The
.Fn reallocarray
function first appeared in
.Ox 5.6 .
.Fn reallocarray
was redesigned in
.Nx 8
as
.Fn reallocarr 3 .
Until
.Nx 10 ,
.Nm
was available 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 .
.Pp
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?)
For this reason
.Nx
decided to go with an alternative implementation, and created
.Xr reallocarr 3 .