[src/trunk]: src/lib/libc/stdlib Move the examples to where they belong, in E...

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

details:   https://anonhg.NetBSD.org/src/rev/10f73e75d5d5
branches:  trunk
changeset: 754526:10f73e75d5d5
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Mon May 03 05:11:34 2010 +0000

description:
Move the examples to where they belong, in EXAMPLES.

diffstat:

 lib/libc/stdlib/malloc.3 |  116 +++++++++++++++++++++++-----------------------
 1 files changed, 59 insertions(+), 57 deletions(-)

diffs (144 lines):

diff -r 8f819306c85d -r 10f73e75d5d5 lib/libc/stdlib/malloc.3
--- a/lib/libc/stdlib/malloc.3  Mon May 03 05:01:53 2010 +0000
+++ b/lib/libc/stdlib/malloc.3  Mon May 03 05:11:34 2010 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: malloc.3,v 1.35 2010/05/03 05:01:53 jruoho Exp $
+.\" $NetBSD: malloc.3,v 1.36 2010/05/03 05:11:34 jruoho Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -78,29 +78,6 @@
 with the exception that the allocated memory is explicitly initialized
 to zero bytes.
 .Pp
-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, "overflow");
-}
-.Ed
-.Pp
 The
 .Fn realloc
 function changes the size of the previously allocated memory referenced by
@@ -129,39 +106,6 @@
 .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
-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 one knows the allocation has been successful.
-This can cause aberrant program behavior if the incorrect size value is used.
-In most cases, the above sample will also 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
-newsize = size + 50;
-
-if ((p2 = realloc(p, newsize)) == NULL) {
-       if (p)
-               free(p);
-       p = NULL;
-       return (NULL);
-}
-
-p = p2;
-size = newsize;
-.Ed
-.Pp
 The
 .Fn free
 function causes the allocated memory referenced by
@@ -205,6 +149,64 @@
 The
 .Fn free
 function returns no value.
+.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 SEE ALSO
 .\" .Xr limits 1 ,
 .Xr madvise 2 ,