Mon Jul 20 12:10:03 2009 UTC ()
Re-add explanation of how to correctly use realloc.


(pooka)
diff -r1.29 -r1.30 src/lib/libc/stdlib/malloc.3
cvs diff -r1.29 -r1.30 src/lib/libc/stdlib/malloc.3 (expand / switch to unified diff)

--- src/lib/libc/stdlib/malloc.3 2009/05/18 09:00:02 1.29
+++ src/lib/libc/stdlib/malloc.3 2009/07/20 12:10:03 1.30
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: malloc.3,v 1.29 2009/05/18 09:00:02 wiz Exp $ 1.\" $NetBSD: malloc.3,v 1.30 2009/07/20 12:10:03 pooka Exp $
2.\" 2.\"
3.\" Copyright (c) 1980, 1991, 1993 3.\" Copyright (c) 1980, 1991, 1993
4.\" The Regents of the University of California. All rights reserved. 4.\" The Regents of the University of California. All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to Berkeley by 6.\" This code is derived from software contributed to Berkeley by
7.\" the American National Standards Committee X3, on Information 7.\" the American National Standards Committee X3, on Information
8.\" Processing Systems. 8.\" Processing Systems.
9.\" 9.\"
10.\" Redistribution and use in source and binary forms, with or without 10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions 11.\" modification, are permitted provided that the following conditions
12.\" are met: 12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright 13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer. 14.\" notice, this list of conditions and the following disclaimer.
@@ -24,27 +24,27 @@ @@ -24,27 +24,27 @@
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE. 32.\" SUCH DAMAGE.
33.\" 33.\"
34.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93 34.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93
35.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $ 35.\" $FreeBSD: src/lib/libc/stdlib/malloc.3,v 1.73 2007/06/15 22:32:33 jasone Exp $
36.\" 36.\"
37.Dd October 15, 2007 37.Dd June 20, 2009
38.Dt MALLOC 3 38.Dt MALLOC 3
39.Os 39.Os
40.Sh NAME 40.Sh NAME
41.Nm malloc , calloc , realloc , free 41.Nm malloc , calloc , realloc , free
42.Nd general purpose memory allocation functions 42.Nd general purpose memory allocation functions
43.Sh LIBRARY 43.Sh LIBRARY
44.Lb libc 44.Lb libc
45.Sh SYNOPSIS 45.Sh SYNOPSIS
46.In stdlib.h 46.In stdlib.h
47.Ft void * 47.Ft void *
48.Fn malloc "size_t size" 48.Fn malloc "size_t size"
49.Ft void * 49.Ft void *
50.Fn calloc "size_t number" "size_t size" 50.Fn calloc "size_t number" "size_t size"
@@ -96,26 +96,56 @@ Note that @@ -96,26 +96,56 @@ Note that
96.Fn realloc 96.Fn realloc
97may move the memory allocation, resulting in a different return value than 97may move the memory allocation, resulting in a different return value than
98.Fa ptr . 98.Fa ptr .
99If 99If
100.Fa ptr 100.Fa ptr
101is 101is
102.Dv NULL , 102.Dv NULL ,
103the 103the
104.Fn realloc 104.Fn realloc
105function behaves identically to 105function behaves identically to
106.Fn malloc 106.Fn malloc
107for the specified size. 107for the specified size.
108.Pp 108.Pp
 109When using
 110.Fn realloc
 111one must be careful to avoid the following idiom:
 112.Pp
 113.Bd -literal -offset indent
 114nsize += 50;
 115if ((p = realloc(p, nsize)) == NULL)
 116 return (NULL);
 117.Ed
 118.Pp
 119Do not adjust the variable describing how much memory has been allocated
 120until one knows the allocation has been successful.
 121This can cause aberrant program behavior if the incorrect size value is used.
 122In most cases, the above sample will also result in a leak of memory.
 123As stated earlier, a return value of
 124.Dv NULL
 125indicates that the old object still remains allocated.
 126Better code looks like this:
 127.Bd -literal -offset indent
 128newsize = size + 50;
 129if ((p2 = realloc(p, newsize)) == NULL) {
 130 if (p)
 131 free(p);
 132 p = NULL;
 133 return (NULL);
 134}
 135p = p2;
 136size = newsize;
 137.Ed
 138.Pp
109The 139The
110.Fn free 140.Fn free
111function causes the allocated memory referenced by 141function causes the allocated memory referenced by
112.Fa ptr 142.Fa ptr
113to be made available for future allocations. 143to be made available for future allocations.
114If 144If
115.Fa ptr 145.Fa ptr
116is 146is
117.Dv NULL , 147.Dv NULL ,
118no action occurs. 148no action occurs.
119.Sh TUNING 149.Sh TUNING
120Once, when the first call is made to one of these memory allocation 150Once, when the first call is made to one of these memory allocation
121routines, various flags will be set or reset, which affect the 151routines, various flags will be set or reset, which affect the