1.\" $NetBSD: reallocarray.3,v 1.7 2022/12/04 11:25:08 uwe Exp $ 2.\" 3.\" Copyright (c) 2015 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in 14.\" the documentation and/or other materials provided with the 15.\" distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 20.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 21.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING, 23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 24.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 25.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 26.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 27.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd September 9, 2022 31.Dt REALLOCARRAY 3 32.Os 33.Sh NAME 34.Nm reallocarray 35.Nd reallocate memory for an array of elements checking for overflow 36.Sh SYNOPSIS 37.In stdlib.h 38.Ft void * 39.Fo reallocarray 40.Fa "void *ptr" 41.Fa "size_t nmemb" 42.Fa "size_t size" 43.Fc 44.Sh DESCRIPTION 45The 46.Fn reallocarray 47function reallocates the pointer 48.Fa ptr 49to a size appropriate to handle an allocation of 50.Fa nmemb 51elements in an array where each of the array elements is 52.Fa size 53bytes using 54.Xr realloc 3 55and making sure that overflow does not happen in the multiplication of 56.Dq "nmemb * size" . 57Otherwise it behaves like 58.Xr realloc 3 . 59.Sh RETURN VALUES 60The 61.Fn reallocarray 62function will return 63.Dv NULL 64if there was overflow or if 65.Xr realloc 3 66failed setting 67.Va errno 68to 69.Er ENOMEM 70or preserving the value from 71.Xr realloc 3 . 72.Sh SEE ALSO 73.Xr malloc 3 , 74.Xr realloc 3 , 75.Xr reallocarr 3 76.\" .Sh STANDARDS 77.\" Will be part of POSIX, but isn't yet. 78.Sh HISTORY 79The 80.Fn reallocarray 81function first appeared in 82.Ox 5.6 . 83.Fn reallocarray 84was redesigned in 85.Nx 8 86as 87.Fn reallocarr 3 . 88Until 89.Nx 10 , 90.Nm 91was available in the 92.Vt _OPENBSD_SOURCE 93namespace. 94.Sh CAVEATS 95The 96.Fn reallocarray 97function was designed to facilitate safe, 98robust programming and overcome the shortcomings of the 99.Xr malloc 3 100and 101.Xr realloc 3 102functions by centralizing the overflow check in the multiplication of 103.Fa nmemb 104and 105.Fa size . 106.Pp 107There are still portability issues. 108(It does not solve the 109.Dv 0 110sized allocation return ambiguity in the C standard: does 111.Fn reallocarray 112return 113.Dv NULL 114or a unique pointer to memory that cannot be accessed? 115Does a 116.Dv NULL 117mean that an error occurred, and can someone check 118.Dv errno 119in that case to find out what happened?) 120For this reason 121.Nx 122decided to go with an alternative implementation, and created 123.Xr reallocarr 3 . 124