[src/trunk]: src/lib/libc/stdlib Revert addition to reallocarray to the mallo...

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/792f947b93b3
branches:  trunk
changeset: 335996:792f947b93b3
user:      christos <christos%NetBSD.org@localhost>
date:      Thu Feb 05 20:02:28 2015 +0000

description:
Revert addition to reallocarray to the malloc man page, but keep
the examples.  Add separate manual page to reallocarray explaining
what are the problems with it.

diffstat:

 lib/libc/stdlib/Makefile.inc   |    5 +-
 lib/libc/stdlib/malloc.3       |   48 ++++-------------
 lib/libc/stdlib/reallocarray.3 |  110 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 124 insertions(+), 39 deletions(-)

diffs (267 lines):

diff -r f401bbfb9502 -r 792f947b93b3 lib/libc/stdlib/Makefile.inc
--- a/lib/libc/stdlib/Makefile.inc      Thu Feb 05 16:50:19 2015 +0000
+++ b/lib/libc/stdlib/Makefile.inc      Thu Feb 05 20:02:28 2015 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile.inc,v 1.87 2015/02/05 16:04:35 christos Exp $
+#      $NetBSD: Makefile.inc,v 1.88 2015/02/05 20:02:28 christos Exp $
 #      from: @(#)Makefile.inc  8.3 (Berkeley) 2/4/95
 
 # stdlib sources
@@ -52,7 +52,7 @@
        malloc.3 memory.3 mi_vector_hash.3 \
        posix_memalign.3 posix_openpt.3 ptsname.3 \
        qabs.3 qdiv.3 quick_exit.3 qsort.3 \
-       radixsort.3 rand48.3 rand.3 random.3 \
+       radixsort.3 rand48.3 rand.3 random.3 reallocarray.3 \
        strfmon.3 strsuftoll.3 strtod.3 strtol.3 strtoul.3 strtonum.3 \
        system.3 \
        tsearch.3 \
@@ -74,7 +74,6 @@
 MLINKS+=insque.3 remque.3
 MLINKS+=lsearch.3 lfind.3
 MLINKS+=malloc.3 calloc.3 malloc.3 realloc.3 malloc.3 free.3
-MLINKS+=malloc.3 reallocarray.3
 MLINKS+=qsort.3 heapsort.3 qsort.3 mergesort.3
 MLINKS+=ptsname.3 ptsname_r.3
 MLINKS+=rand.3 rand_r.3
diff -r f401bbfb9502 -r 792f947b93b3 lib/libc/stdlib/malloc.3
--- a/lib/libc/stdlib/malloc.3  Thu Feb 05 16:50:19 2015 +0000
+++ b/lib/libc/stdlib/malloc.3  Thu Feb 05 20:02:28 2015 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: malloc.3,v 1.39 2015/02/05 16:04:35 christos Exp $
+.\" $NetBSD: malloc.3,v 1.40 2015/02/05 20:02:28 christos Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -38,7 +38,7 @@
 .Dt MALLOC 3
 .Os
 .Sh NAME
-.Nm malloc , calloc , realloc , reallocarray, free
+.Nm malloc , calloc , realloc , free
 .Nd general purpose memory allocation functions
 .Sh LIBRARY
 .Lb libc
@@ -50,8 +50,6 @@
 .Fn calloc "size_t number" "size_t size"
 .Ft void *
 .Fn realloc "void *ptr" "size_t size"
-.Ft void *
-.Fn reallocarray "void *ptr" "size_t number" "size_t size"
 .Ft void
 .Fn free "void *ptr"
 .Sh DESCRIPTION
@@ -76,7 +74,7 @@
 with an argument of
 .Dq "number * size" ,
 with the exception that the allocated memory is explicitly initialized
-to zero bytes, and overflow is being checked.
+to zero bytes.
 .Pp
 The
 .Fn realloc
@@ -93,21 +91,8 @@
 .Fa ptr
 is freed and a pointer to the newly allocated memory is returned.
 .Pp
-The
-.Fn reallocarray
-function is similar to
-.Fn realloc
-except it operates on
-.Fa number
-members of size
-.Fa size
-and checks for integer overflow in the calculation of\
-.Dq "number * size" .
-.Pp
 Note that
 .Fn realloc
-and
-.Fn reallocarray
 may move the memory allocation, resulting in a different return value than
 .Fa ptr .
 If
@@ -145,9 +130,7 @@
 .Pp
 The
 .Fn realloc
-and
-.Fn reallocarray
-functions return a pointer, possibly identical to
+function returns a pointer, possibly identical to
 .Fa ptr ,
 to the allocated memory
 if successful; otherwise a
@@ -159,9 +142,7 @@
 if the error was the result of an allocation failure.
 The
 .Fn realloc
-and
-.Fn reallocarray
-functions always leave the original buffer intact
+function always leaves the original buffer intact
 when an error occurs.
 .Pp
 The
@@ -178,7 +159,7 @@
 .Pp
 The multiplication may lead to an integer overflow.
 To avoid this,
-.Fn reallocarray
+.Xr reallocarr 3
 is recommended.
 .Pp
 If
@@ -214,12 +195,13 @@
 does, it is much easier to use
 .Fn calloc
 or 
-.Fn reallocarray .
+.Xr reallocarr 3 .
 .Pp
 The above examples could be simplified to:
 .Bd -literal -offset indent
-if ((p = reallocarray(NULL, num, size)) == NULL) 
-       err(1, "reallocarray");
+ptr = NULL;
+if ((e = reallocarr(&ptr, num, size))) 
+       errx(1, "reallocarr", strerror(e));
 .Ed
 .Bd -literal -offset indent
 or at the cost of initialization:
@@ -270,7 +252,8 @@
 .Xr atexit 3 ,
 .Xr getpagesize 3 ,
 .Xr memory 3 ,
-.Xr posix_memalign 3
+.Xr posix_memalign 3 ,
+.Xr reallocarr 3
 .Pp
 For the implementation details, see
 .Xr jemalloc 3 .
@@ -283,10 +266,3 @@
 .Fn free
 functions conform to
 .St -isoC .
-.Pp
-The
-.Fn reallocarray
-function first appeared on
-.Ox 5.6
-and
-.Nx 8 .
diff -r f401bbfb9502 -r 792f947b93b3 lib/libc/stdlib/reallocarray.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/stdlib/reallocarray.3    Thu Feb 05 20:02:28 2015 +0000
@@ -0,0 +1,110 @@
+.\" $NetBSD: reallocarray.3,v 1.1 2015/02/05 20:02:28 christos Exp $
+.\"
+.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
+Implementation issues prevent the function from being used correctly (a
+.Dv 0
+.Fa size
+parameter will return
+.Dv ENOMEM
+in the
+.Ox
+implementation), while there are still portability issues (it does not solve
+the 
+.Dv 0
+sized allocation return ambiguity: 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 those reasons
+.Nx
+decided to go with an alternative implementation, and created
+.Xr reallocarr 3 .