From: Sascha Wildner <saw@online.de>
Date: Fri, 21 May 2010 20:09:48 +0000 (+0200)
Subject: malloc.3: Sort of sync with NetBSD (for the examples, mainly).
X-Git-Tag: v2.9.0~990
X-Git-Url: https://gitweb.dragonflybsd.org/dragonfly.git/commitdiff_plain/899b08f0481cee99aeea3b0d44cd623a9d6bc2db

malloc.3: Sort of sync with NetBSD (for the examples, mainly).
---

diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3
index e73f083428..3275743a48 100644
--- a/lib/libc/stdlib/malloc.3
+++ b/lib/libc/stdlib/malloc.3
@@ -1,3 +1,5 @@
+.\" $NetBSD: malloc.3,v 1.38 2010/05/03 08:23:20 jruoho Exp $
+.\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"	The Regents of the University of California.  All rights reserved.
 .\"
@@ -34,18 +36,17 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)malloc.3	8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.25.2.16 2003/01/06 17:10:45 trhodes Exp $
-.\" $DragonFly: src/lib/libc/stdlib/malloc.3,v 1.8 2008/05/02 02:05:04 swildner Exp $
+.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $
 .\"
-.Dd May 2, 2009
+.Dd May 21, 2010
 .Dt MALLOC 3
 .Os
 .Sh NAME
 .Nm malloc ,
 .Nm calloc ,
 .Nm realloc ,
+.Nm reallocf ,
 .Nm free ,
-.Nm reallocf
 .Nd general purpose memory allocation functions
 .Sh LIBRARY
 .Lb libc
@@ -66,7 +67,7 @@ The
 .Fn malloc
 function allocates
 .Fa size
-bytes of memory.
+bytes of uninitialized memory.
 The allocated space is suitably aligned (after possible pointer coercion)
 for storage of any type of object.
 If the space is at least
@@ -74,17 +75,6 @@ If the space is at least
 bytes in length (see
 .Xr getpagesize 3 ) ,
 the returned memory will be page boundary aligned as well.
-If
-.Fn malloc
-fails, a
-.Dv NULL
-pointer is returned.
-.Pp
-Note that
-.Fn malloc
-does
-.Em NOT
-normally initialize the returned memory to zero bytes.
 .Pp
 The
 .Fn calloc
@@ -97,7 +87,7 @@ bytes in length.
 The result is identical to calling
 .Fn malloc
 with an argument of
-.Dq Fa number * Fa size ,
+.Dq "number * size" ,
 with the exception that the allocated memory is explicitly initialized
 to zero bytes.
 .Pp
@@ -112,12 +102,13 @@ The contents of the memory are unchanged up to the lesser of the new and
 old sizes.
 If the new size is larger,
 the value of the newly allocated portion of the memory is undefined.
-If the requested memory cannot be allocated,
-.Dv NULL
-is returned and
-the memory referenced by
+Upon success, the memory referenced by
 .Fa ptr
-is valid and unchanged.
+is freed and a pointer to the newly allocated memory is returned.
+Note that
+.Fn realloc
+may move the memory allocation, resulting in a different return value than
+.Fa ptr .
 If
 .Fa ptr
 is
@@ -249,7 +240,65 @@ deallocates it in this case.
 The
 .Fn free
 function returns no value.
-.Sh DIAGNOSTIC MESSAGES
+.Sh EXAMPLES
+When using
+.Fn malloc ,
+be careful to avoid the following idiom:
+.Bd -literal -offset indent
+if ((p = malloc(number * size)) == NULL)
+	err(EXIT_FAILURE, "malloc");
+.Ed
+.Pp
+The multiplication may lead to an integer overflow.
+To avoid this,
+.Fn calloc
+is recommended.
+.Pp
+If
+.Fn malloc
+must be used, be sure to test for overflow:
+.Bd -literal -offset indent
+if (size && number > SIZE_MAX / size) {
+	errno = EOVERFLOW;
+	err(EXIT_FAILURE, "allocation");
+}
+.Ed
+.Pp
+When using
+.Fn realloc ,
+one must be careful to avoid the following idiom:
+.Pp
+.Bd -literal -offset indent
+nsize += 50;
+
+if ((p = realloc(p, nsize)) == NULL)
+	return NULL;
+.Ed
+.Pp
+Do not adjust the variable describing how much memory has been allocated
+until it is known that the allocation has been successful.
+This can cause aberrant program behavior if the incorrect size value is used.
+In most cases, the above example will also leak memory.
+As stated earlier, a return value of
+.Dv NULL
+indicates that the old object still remains allocated.
+Better code looks like this:
+.Bd -literal -offset indent
+newsize = size + 50;
+
+if ((p2 = realloc(p, newsize)) == NULL) {
+
+	if (p != NULL)
+		free(p);
+
+	p = NULL;
+	return NULL;
+}
+
+p = p2;
+size = newsize;
+.Ed
+.Sh DIAGNOSTICS
 If
 .Fn malloc ,
 .Fn calloc ,
@@ -260,9 +309,11 @@ detect an error, a message will be printed to file descriptor
 .Dv STDERR_FILENO
 and the process will dump core.
 .Sh SEE ALSO
-.Xr brk 2 ,
+.Xr madvise 2 ,
 .Xr mmap 2 ,
+.Xr sbrk 2 ,
 .Xr alloca 3 ,
+.Xr atexit 3 ,
 .Xr getpagesize 3 ,
 .Xr memory 3 ,
 .Xr posix_memalign 3