1.\" $NetBSD: reallocarray.3,v 1.4 2015/07/26 02:29:44 kamil 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 February 5, 2015 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.Vt #define _OPENBSD_SOURCE 38.In stdlib.h 39.Ft void * 40.Fo reallocarray 41.Fa "void *ptr" 42.Fa "size_t nmemb" 43.Fa "size_t size" 44.Fc 45.Sh DESCRIPTION 46The 47.Fn reallocarray 48function reallocates the pointer 49.Fa ptr 50to a size appropriate to handle an allocation of 51.Fa nmemb 52elements in an array where each of the array elements is 53.Fa size 54bytes using 55.Xr realloc 3 56and making sure that overflow does not happen in the multiplication of 57.Dq "nmemb * size" . 58.Pp 59This function is provided for source compatibility with 60.Ox 61and 62its use is discouraged in preference to 63.Xr reallocarr 3 . 64.Sh RETURN VALUES 65The 66.Fn reallocarray 67function will return 68.Dv NULL 69if there was overflow or if 70.Xr realloc 3 71failed setting 72.Va errno 73to 74.Dv EOVERFLOW 75or preserving the value from 76.Xr realloc 3 . 77.Sh SEE ALSO 78.Xr malloc 3 , 79.Xr realloc 3 , 80.Xr reallocarr 3 81.Sh STANDARDS 82.Fn reallocarray 83is an 84.Ox 85extension. 86.Sh HISTORY 87The 88.Fn reallocarray 89function first appeared in 90.Ox 5.6 . 91.Fn reallocarray 92was redesigned in 93.Nx 8 94as 95.Fn reallocarr 3 . 96For compatibility reasons it's available since 97.Nx 8 98in the 99.Vt _OPENBSD_SOURCE 100namespace. 101.Sh CAVEATS 102The 103.Fn reallocarray 104function was designed to facilitate safe, 105robust programming and overcome the shortcomings of the 106.Xr malloc 3 107and 108.Xr realloc 3 109functions by centralizing the overflow check in the multiplication of 110.Fa nmemb 111and 112.Fa size . 113.Pp 114There are still portability issues (it does not solve 115the 116.Dv 0 117sized allocation return ambiguity in the C standard: does 118.Fn reallocarray 119return 120.Dv NULL 121or a unique pointer to memory that cannot be accessed? Does a 122.Dv NULL 123mean that an error occurred, and can someone check 124.Dv errno 125in that case to find out what happened?). 126.Pp 127For this reason 128.Nx 129decided to go with an alternative implementation, and created 130.Xr reallocarr 3 . 131