lib/libc/stdlib/reallocarray.3

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