malloc.3: Add 'reallocarray' in NAME

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

diff --git a/man3/malloc.3 b/man3/malloc.3
index efe2be30c8b9cf5e4f800842a94afa8c6e4c65f4..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,13 +31,13 @@
 .\" FIXME . Review http://austingroupbugs.net/view.php?id=374
 .\" to see what changes are required on this page.
 .\"
-.TH MALLOC 3  2015-08-08 "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>
-.sp
+.PP
 .BI "void *malloc(size_t " "size" );
 .BI "void free(void " "*ptr" );
 .BI "void *calloc(size_t " "nmemb" ", size_t " "size" );
@@ -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 ()
@@ -286,14 +308,16 @@ bytes, the glibc
 implementation allocates the memory as a private anonymous mapping using
 .BR mmap (2).
 .B MMAP_THRESHOLD
-is 128 kB by default, but is adjustable using
+is 128\ kB by default, but is adjustable using
 .BR mallopt (3).
-Allocations performed using
+Prior to Linux 4.7
+allocations performed using
 .BR mmap (2)
-are unaffected by the
+were unaffected by the
 .B RLIMIT_DATA
-resource limit (see
-.BR getrlimit (2)).
+resource limit;
+since Linux 4.7, this limit is also enforced for allocations performed using
+.BR mmap (2).
 .PP
 To avoid corruption in multithreaded applications,
 mutexes are used internally to protect the memory-management
@@ -330,7 +354,7 @@ use a private malloc implementation that does not set
 then certain library routines may fail without having
 a reason in
 .IR errno .
-.LP
+.PP
 Crashes in
 .BR malloc (),
 .BR calloc (),
@@ -358,6 +382,7 @@ for details.
 .\"
 .ad l
 .nh
+.BR valgrind (1),
 .BR brk (2),
 .BR mmap (2),
 .BR alloca (3),
@@ -369,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 .