Add new man page for reallocarray(3)

Import man page from OpenBSD.

Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=85622

diff --git a/man/Makefile.am b/man/Makefile.am
index 4e57553bf5c329a5001d9b36889786c2ee7a564b..1456ef7e64e47c65272335cc6ae5bd48ff73c101 100644 (file)
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -42,6 +42,7 @@ dist_man_MANS = \
        queue.3bsd \
        radixsort.3 \
        readpassphrase.3 \
+       reallocarray.3 \
        reallocf.3 \
        setmode.3 \
        setproctitle.3 \

diff --git a/man/reallocarray.3 b/man/reallocarray.3
new file mode 100644 (file)
index 0000000..71a047e
--- /dev/null
+++ b/man/reallocarray.3
@@ -0,0 +1,102 @@
+.\"
+.\" Copyright (c) 1980, 1991, 1993
+.\"    The Regents of the University of California.  All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" the American National Standards Committee X3, on Information
+.\" Processing Systems.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"    $OpenBSD: malloc.3,v 1.78 2014/05/01 18:41:59 jmc Exp $
+.\"
+.Dd $Mdocdate: May 1 2014 $
+.Dt MALLOC 3
+.Os
+.Sh NAME
+.Nm reallocarray
+.Nd memory allocation and deallocation
+.Sh LIBRARY
+.ds str-Lb-libbsd Utility functions from BSD systems (libbsd, \-lbsd)
+.Lb libbsd
+.Sh SYNOPSIS
+.In bsd/stdlib.h
+.Ft void *
+.Fn reallocarray "void *ptr" "size_t nmemb" "size_t size"
+.Sh DESCRIPTION
+.Pp
+When using
+.Fn malloc
+be careful to avoid the following idiom:
+.Bd -literal -offset indent
+if ((p = malloc(num * size)) == NULL)
+       err(1, "malloc");
+.Ed
+.Pp
+The multiplication may lead to an integer overflow, which can
+be avoided using the extension
+.Fn reallocarray ,
+as follows:
+.Bd -literal -offset indent
+if ((p = reallocarray(NULL, num, size)) == NULL)
+       err(1, "malloc");
+.Ed
+.Pp
+Alternatively
+.Fn calloc
+is a more portable solution which comes with the cost of clearing memory.
+.Pp
+If
+.Fn malloc
+must be used, be sure to test for overflow:
+.Bd -literal -offset indent
+if (size && num > SIZE_MAX / size) {
+       errno = ENOMEM;
+       err(1, "overflow");
+}
+.Ed
+.Pp
+The use of
+.Fn reallocarray
+or
+.Fn calloc
+is strongly encouraged when allocating multiple sized objects
+in order to avoid possible integer overflows.
+.Sh RETURN VALUES
+The
+.Fn reallocarray
+function returns a pointer to the allocated space if successful; otherwise,
+a null pointer is returned and
+.Va errno
+is set to
+.Er ENOMEM .
+.Sh SEE ALSO
+.Xr malloc 3 ,
+.Xr calloc 3 ,
+.Xr alloca 3
+.Sh HISTORY
+.Fn reallocarray
+appeared in
+.Ox 5.6 .