malloc.3: Add 'reallocarray' in NAME

[thirdparty/man-pages.git] / man3 / malloc.3

diff --git a/man3/malloc.3 b/man3/malloc.3
index db508018404ca829b1a730fbb49d831d973664d2..f38c7baca7b0e35c1ce52227e56e76d3da340736 100644 (file)
--- a/man3/malloc.3
+++ b/man3/malloc.3
@@ -1,4 +1,5 @@
 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
+.\" and Copyright i2007, 2012, 2018, Michael Kerrisk <mtk.manpages@gmail.com>
 .\"
 .\" %%%LICENSE_START(VERBATIM)
 .\" Permission is granted to make and distribute verbatim copies of this
@@ -30,9 +31,9 @@
 .\" FIXME . Review http://austingroupbugs.net/view.php?id=374
 .\" to see what changes are required on this page.
 .\"
-.TH MALLOC 3  2017-07-13 "GNU" "Linux Programmer's Manual"
+.TH MALLOC 3  2020-02-09 "GNU" "Linux Programmer's Manual"
 .SH NAME
-malloc, free, calloc, realloc \- allocate and free dynamic memory
+malloc, free, calloc, realloc, reallocarray \- allocate and free dynamic memory
 .SH SYNOPSIS
 .nf
 .B #include <stdlib.h>
@@ -50,11 +51,11 @@ Feature Test Macro Requirements for glibc (see
 .in
 .PP
 .BR reallocarray ():
-.br
-.RS 4
 .ad l
-_GNU_SOURCE
-.RE
+    Since glibc 2.29:
+        _DEFAULT_SOURCE
+    Glibc 2.28 and earlier:
+        _GNU_SOURCE
 .ad
 .SH DESCRIPTION
 .PP
@@ -107,6 +108,23 @@ returns either NULL,
 .\" glibc does this:
 or a unique pointer value that can later be successfully passed to
 .BR free ().
+If the multiplication of
+.I nmemb
+and
+.I size
+would result in integer overflow, then
+.BR calloc ()
+returns an error.
+By contrast,
+an integer overflow would not be detected in the following call to
+.BR malloc (),
+with the result that an incorrectly sized block of memory would be allocated:
+.PP
+.in +4n
+.EX
+malloc(nmemb * size);
+.EE
+.in
 .PP
 The
 .BR realloc ()
@@ -199,9 +217,13 @@ function returns no value.
 The
 .BR realloc ()
 function returns a pointer to the newly allocated memory, which is suitably
-aligned for any built-in type and may be different from
-.IR ptr ,
-or NULL if the request fails.
+aligned for any built-in type, or NULL if the request failed.
+The returned pointer may be the same as
+.IR ptr
+if the allocation was not moved
+(e.g., there was room to expand the allocation in-place), or different from
+.IR ptr
+if the allocation was moved to a new address.
 If
 .I size
 was equal to 0, either NULL or a pointer suitable to be passed to
@@ -272,7 +294,7 @@ and
 in
 .BR proc (5),
 and the Linux kernel source file
-.IR Documentation/vm/overcommit-accounting .
+.IR Documentation/vm/overcommit-accounting.rst .
 .PP
 Normally,
 .BR malloc ()
@@ -360,6 +382,7 @@ for details.
 .\"
 .ad l
 .nh
+.BR valgrind (1),
 .BR brk (2),
 .BR mmap (2),
 .BR alloca (3),
@@ -371,3 +394,7 @@ for details.
 .BR mcheck (3),
 .BR mtrace (3),
 .BR posix_memalign (3)
+.PP
+For details of the GNU C library implementation, see
+.UR https://sourceware.org/glibc/wiki/MallocInternals
+.UE .