Module Name: src
Committed By: christos
Date: Thu Feb 5 20:02:29 UTC 2015
Modified Files:
src/lib/libc/stdlib: Makefile.inc malloc.3
Added Files:
src/lib/libc/stdlib: reallocarray.3
Log Message:
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.
To generate a diff of this commit:
cvs rdiff -u -r1.87 -r1.88 src/lib/libc/stdlib/Makefile.inc
cvs rdiff -u -r1.39 -r1.40 src/lib/libc/stdlib/malloc.3
cvs rdiff -u -r0 -r1.1 src/lib/libc/stdlib/reallocarray.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/stdlib/Makefile.inc
diff -u src/lib/libc/stdlib/Makefile.inc:1.87 src/lib/libc/stdlib/Makefile.inc:1.88
--- src/lib/libc/stdlib/Makefile.inc:1.87 Thu Feb 5 11:04:35 2015
+++ src/lib/libc/stdlib/Makefile.inc Thu Feb 5 15:02:28 2015
@@ -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 @@ MAN+= a64l.3 abort.3 abs.3 alloca.3 atex
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+=hcreate.3 hdestroy1.3 hcreate.3
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
Index: src/lib/libc/stdlib/malloc.3
diff -u src/lib/libc/stdlib/malloc.3:1.39 src/lib/libc/stdlib/malloc.3:1.40
--- src/lib/libc/stdlib/malloc.3:1.39 Thu Feb 5 11:04:35 2015
+++ src/lib/libc/stdlib/malloc.3 Thu Feb 5 15:02:28 2015
@@ -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 @@ The result is identical to calling
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 @@ Upon success, the memory referenced by
.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 @@ is set to
.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 @@ is set to
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 @@ if ((p = malloc(number * size)) == NULL)
.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 @@ Assuming the implementation checks for i
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 @@ size = newsize;
.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 @@ and
.Fn free
functions conform to
.St -isoC .
-.Pp
-The
-.Fn reallocarray
-function first appeared on
-.Ox 5.6
-and
-.Nx 8 .
Added files:
Index: src/lib/libc/stdlib/reallocarray.3
diff -u /dev/null src/lib/libc/stdlib/reallocarray.3:1.1
--- /dev/null Thu Feb 5 15:02:29 2015
+++ src/lib/libc/stdlib/reallocarray.3 Thu Feb 5 15:02:28 2015
@@ -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 .
