From 12ec54b4088752df29f5bb626353f9dc99fdfec9 Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Fri, 1 Oct 2010 20:18:07 +0200
Subject: [PATCH] malloc.3: Various minor reorganizations and wording fix-ups

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man3/malloc.3 | 95 +++++++++++++++++++++++++++------------------------
 1 file changed, 50 insertions(+), 45 deletions(-)

diff --git a/man3/malloc.3 b/man3/malloc.3
index 8f86849c5..0d346f2c1 100644
--- a/man3/malloc.3
+++ b/man3/malloc.3
@@ -25,24 +25,54 @@
 .\" Documented MALLOC_CHECK_, Wolfram Gloger (wmglo@dent.med.uni-muenchen.de)
 .\" 2007-09-15 mtk: added notes on malloc()'s use of sbrk() and mmap().
 .\"
-.TH MALLOC 3  2009-01-13 "GNU" "Linux Programmer's Manual"
+.TH MALLOC 3  2010-10-02 "GNU" "Linux Programmer's Manual"
 .SH NAME
-calloc, malloc, free, realloc \- Allocate and free dynamic memory
+malloc, free, calloc, realloc \- Allocate and free dynamic memory
 .SH SYNOPSIS
 .nf
 .B #include <stdlib.h>
 .sp
-.BI "void *calloc(size_t " "nmemb" ", size_t " "size" );
-.br
 .BI "void *malloc(size_t " "size" );
-.br
 .BI "void free(void " "*ptr" );
-.br
 .BI "void *realloc(void " "*ptr" ", size_t "  "size" );
+.BI "void *calloc(size_t " "nmemb" ", size_t " "size" );
 .fi
 .SH DESCRIPTION
+.PP
+The
+.BR malloc ()
+function allocates
+.I size
+bytes and returns a pointer to the allocated memory.
+The memory is not cleared.
+If
+.I size
+is 0, then
+.BR malloc ()
+returns either NULL,
+.\" glibc does this:
+or a unique pointer value that can later be successfully passed to
+.BR free ().
+.PP
+The
+.BR free ()
+function frees the memory space pointed to by
+.IR ptr ,
+which must have been returned by a previous call to
+.BR malloc (),
 .BR calloc ()
-allocates memory for an array of
+or
+.BR realloc ().
+Otherwise, or if
+.I free(ptr)
+has already been called before, undefined behavior occurs.
+If
+.I ptr
+is NULL, no operation is performed.
+.PP
+The
+.BR calloc ()
+function allocates memory for an array of
 .I nmemb
 elements of
 .I size
@@ -59,42 +89,15 @@ returns either NULL,
 or a unique pointer value that can later be successfully passed to
 .BR free ().
 .PP
-.BR malloc ()
-allocates
-.I size
-bytes and returns a pointer to the allocated memory.
-The memory is not cleared.
-If
-.I size
-is 0, then
-.BR malloc ()
-returns either NULL,
-.\" glibc does this:
-or a unique pointer value that can later be successfully passed to
-.BR free ().
-.PP
-.BR free ()
-frees the memory space pointed to by
-.IR ptr ,
-which must have been returned by a previous call to
-.BR malloc (),
-.BR calloc ()
-or
-.BR realloc ().
-Otherwise, or if
-.I free(ptr)
-has already been called before, undefined behavior occurs.
-If
-.I ptr
-is NULL, no operation is performed.
-.PP
+The
 .BR realloc ()
-changes the size of the memory block pointed to by
+function changes the size of the memory block pointed to by
 .I ptr
 to
 .I size
 bytes.
-The contents will be unchanged to the minimum of the old and new sizes;
+The contents will be unchanged n the range from the start of the region
+up to the minimum of the old and new sizes;
 newly allocated memory will be uninitialized.
 If
 .I ptr
@@ -120,12 +123,12 @@ If the area pointed to was moved, a
 .I free(ptr)
 is done.
 .SH "RETURN VALUE"
-For
-.BR calloc ()
+The
+.BR malloc ()
 and
-.BR malloc (),
-return a pointer to the allocated memory, which is suitably
-aligned for any kind of variable.
+.BR calloc ()
+functions return a pointer to the allocated memory
+that is suitably aligned for any kind of variable.
 On error, these functions return NULL.
 NULL may also be returned by a successful call to
 .BR malloc ()
@@ -140,11 +143,13 @@ or
 .I size
 equal to zero.
 .PP
+The
 .BR free ()
-returns no value.
+function returns no value.
 .PP
+The
 .BR realloc ()
-returns a pointer to the newly allocated memory, which is suitably
+function returns a pointer to the newly allocated memory, which is suitably
 aligned for any kind of variable and may be different from
 .IR ptr ,
 or NULL if the request fails.