xref: /minix3/lib/libc/stdlib/reallocarray.3 (revision 0a6a1f1d05b60e214de2f05a7310ddd1f0e590e7)

.\" $NetBSD: reallocarray.3,v 1.4 2015/07/26 02:29:44 kamil 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 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
.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" .
.Pp
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 .
.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?).
.Pp
For this reason
.Nx
decided to go with an alternative implementation, and created
.Xr reallocarr 3 .