[src/trunk]: src/lib/libc/stdlib - more description about realloc.

[yamt <yamt%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/1fd079ac1747
branches:  trunk
changeset: 535136:1fd079ac1747
user:      yamt <yamt%NetBSD.org@localhost>
date:      Sun Aug 11 06:12:45 2002 +0000

description:
- more description about realloc.
- mention errno.
- add FILES section for malloc.conf.
from openbsd.

diffstat:

 lib/libc/stdlib/malloc.3 |  46 +++++++++++++++++++++++++++++++++++++++++-----
 1 files changed, 41 insertions(+), 5 deletions(-)

diffs (95 lines):

diff -r 380e1f8fe360 -r 1fd079ac1747 lib/libc/stdlib/malloc.3
--- a/lib/libc/stdlib/malloc.3  Sun Aug 11 03:59:31 2002 +0000
+++ b/lib/libc/stdlib/malloc.3  Sun Aug 11 06:12:45 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: malloc.3,v 1.15 2002/02/07 07:00:29 ross Exp $
+.\"    $NetBSD: malloc.3,v 1.16 2002/08/11 06:12:45 yamt Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -38,7 +38,7 @@
 .\"     @(#)malloc.3   8.1 (Berkeley) 6/4/93
 .\"     From FreeBSD: Id: malloc.3,v 1.18 1999/03/28 14:16:04 phk Exp
 .\"
-.Dd August 2, 1999
+.Dd August 11, 2002
 .Dt MALLOC 3
 .Os
 .Sh NAME
@@ -103,7 +103,7 @@
 .Fa ptr
 to
 .Fa size
-bytes.
+bytes and returns a pointer to the (possibly moved) object.
 The contents of the memory are unchanged up to the lesser of the new and
 old sizes.
 If the new size is larger,
@@ -119,6 +119,30 @@
 function behaves identically to
 .Fn malloc
 for the specified size.
+.Pp
+When using
+.Fn realloc
+one must be careful to avoid the following idiom:
+.Pp
+.Bd -literal -offset indent
+if ((p = realloc(p, nsize)) == NULL)
+       return NULL;
+.Ed
+.Pp
+In most cases, this will result in a leak of 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
+if ((p2 = realloc(p, nsize)) == NULL) {
+       if (p)
+               free(p);
+       p = NULL;
+       return NULL;
+}
+p = p2;
+.Ed
 .\"XXX".Pp
 .\"XXX"The
 .\"XXX".Fn reallocf
@@ -249,7 +273,10 @@
 and
 .Fn calloc
 functions return a pointer to the allocated memory if successful; otherwise
-a NULL pointer is returned.
+a NULL pointer is returned and
+.Va errno
+is set to
+.Er ENOMEM .
 .Pp
 The
 .Fn realloc
@@ -260,7 +287,11 @@
 a pointer, possibly identical to
 .Fa ptr ,
 to the allocated memory
-if successful; otherwise a NULL pointer is returned, in which case the
+if successful; otherwise a NULL pointer is returned and
+.Va errno
+is set to
+.Er ENOMEM ,
+in which case the
 memory referenced by
 .Fa ptr
 is still available and intact.
@@ -278,6 +309,11 @@
 is set, the characters it contains will be interpreted as flags to the
 allocation functions.
 .El
+.Sh FILES
+.Bl -tag -width "/etc/malloc.conf"
+.It Pa /etc/malloc.conf
+symbolic link to filename containing option flags
+.El
 .Sh EXAMPLES
 To set a systemwide reduction of cache size, and to dump core whenever
 a problem occurs: