lib/libc/stdlib/reallocarray.3

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .Dd May 1, 2015
  30 .Dt REALLOCARRAY 3
  31 .Os
  32 .Sh NAME
  33 .Nm reallocarray
  34 .Nd memory reallocation function
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In stdlib.h
  39 .Ft void *
  40 .Fn reallocarray "void *ptr" "size_t nmemb" "size_t size"
  41 .Sh DESCRIPTION
  42 The
  43 .Fn reallocarray
  44 function is similar to the
  45 .Fn realloc
  46 function
  47 except it operates on
  48 .Fa nmemb
  49 members of size
  50 .Fa size
  51 and checks for integer overflow in the calculation
  52 .Fa nmemb
  53 *
  54 .Fa size .
  55 .Sh RETURN VALUES
  56 The
  57 .Fn reallocarray
  58 function returns a pointer to the allocated space; otherwise, a
  59 .Dv NULL
  60 pointer is returned and
  61 .Va errno
  62 is set to
  63 .Er ENOMEM .
  64 .Sh EXAMPLES
  65 Consider
  66 .Fn reallocarray
  67 when there is multiplication in the
  68 .Fa size
  69 argument of
  70 .Fn malloc
  71 or
  72 .Fn realloc .
  73 For example, avoid this common idiom as it may lead to integer overflow:
  74 .Bd -literal -offset indent
  75 if ((p = malloc(num * size)) == NULL)
  76         err(1, "malloc");
  77 .Ed
  78 .Pp
  79 A drop-in replacement is the
  80 .Ox
  81 extension
  82 .Fn reallocarray :
  83 .Bd -literal -offset indent
  84 if ((p = reallocarray(NULL, num, size)) == NULL)
  85         err(1, "reallocarray");
  86 .Ed
  87 .Pp
  88 When using
  89 .Fn realloc ,
  90 be careful to avoid the following idiom:
  91 .Bd -literal -offset indent
  92 size += 50;
  93 if ((p = realloc(p, size)) == NULL)
  94         return (NULL);
  95 .Ed
  96 .Pp
  97 Do not adjust the variable describing how much memory has been allocated
  98 until the allocation has been successful.
  99 This can cause aberrant program behavior if the incorrect size value is used.
 100 In most cases, the above sample will also result in a leak of memory.
 101 As stated earlier, a return value of
 102 .Dv NULL
 103 indicates that the old object still remains allocated.
 104 Better code looks like this:
 105 .Bd -literal -offset indent
 106 newsize = size + 50;
 107 if ((newp = realloc(p, newsize)) == NULL) {
 108         free(p);
 109         p = NULL;
 110         size = 0;
 111         return (NULL);
 112 }
 113 p = newp;
 114 size = newsize;
 115 .Ed
 116 .Pp
 117 As with
 118 .Fn malloc ,
 119 it is important to ensure the new size value will not overflow;
 120 i.e. avoid allocations like the following:
 121 .Bd -literal -offset indent
 122 if ((newp = realloc(p, num * size)) == NULL) {
 123         ...
 124 .Ed
 125 .Pp
 126 Instead, use
 127 .Fn reallocarray :
 128 .Bd -literal -offset indent
 129 if ((newp = reallocarray(p, num, size)) == NULL) {
 130         ...
 131 .Ed
 132 .Sh SEE ALSO
 133 .Xr realloc 3
 134 .Sh HISTORY
 135 The
 136 .Fn reallocarray
 137 function first appeared in
 138 .Ox 5.6
 139 and
 140 .Fx 11.0 .