memusagestat.1: Various additions and improvements

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man1/memusagestat.1

@@ -20,96 +20,115 @@
 .\" License along with this manual; if not, see
 .\" <http://www.gnu.org/licenses/>.
 .\" %%%LICENSE_END
-.TH MEMUSAGESTAT 1 2013-04-10 "GNU glibc 2.18" "Memory diagnostic tools"
+.TH MEMUSAGESTAT 1 2013-04-10 "GNU" "Linux programmer's manual"
 .SH NAME
 memusagestat \- generate graphic from memory profiling data
 .SH SYNOPSIS
 .BR memusagestat " [\fIoption\fR]... \fIdatafile\fR [\fIoutfile\fR]"
 .SH DESCRIPTION
 .B memusagestat
-can create a PNG file with graphical representation of memory profiling 
+creates a PNG file containing a graphical representation of the
-data.
+memory profiling data in the file
-Red line in the graph shows the heap usage (allocated memory),
+.IR datafile ;
-green line shows the stack usage,
+that file is generated via the
-x-scale number of memory handling functions calls or time (\fB-t\fR option).
+.I -d
-.I datafile
+(or
-is a binary data file generated by
+.IR --data )
-.BR memusage (1)
+option of
-utility with
+.BR memusage (1).
-.B -d
+
-option.
+The red line in the graph shows the heap usage (allocated memory)
+and the green line shows the stack usage.
+The x-scale is either the number of memory-handling function calls or
+(if the
+.I -t
+option is specified)
+time.
 .SH OPTIONS
 .TP
 .BI \-o\  file \fR,\ \fB\-\-output= file
 Name of the output file.
 .TP
 .BI \-s\  string \fR,\ \fB\-\-string= string
-Title string used in the output graphic.
+Use
+.I string
+as the title inside the output graph.
 .TP
 .BI \-t\fR,\ \fB\-\-time
-Generate output linear to time
+Use time (rather than number of function calls) as the scale for the X axis.
-(default is linear to number of function calls).
 .TP
 .BI \-T\fR,\ \fB\-\-total
-Also draw graph for total memory consumption.
+Also draw a graph of total memory consumption.
 .TP
 .BI \-x\  size \fR,\ \fB\-\-x-size= size
-Make graphic size pixels wide.
+Make the output graph
+.I size
+pixels wide.
 .TP
 .BI \-y\  size \fR,\ \fB\-\-y\-size= size
-Make graphic size pixels high.
+Make the output graph
+.I size
+pixels high.
 .TP
 .BI \-?\fR,\ \fB\-\-help
-Print help and exit.
+Print a help message and exit.
 .TP
 .BI \fB\-\-usage
 Print a short usage message and exit.
 .TP
 .BI \-V\fR,\ \fB\-\-version
 Print version information and exit.
-.SH EXAMPLES
+.SH EXAMPLE
-Here is a simple program \fImemusagestatexample.c\fR simulating increase
+Below is a simple program that reallocates a block of 
-and decrease of memory usage:
+memory in cycles that rise to a peak before then cyclically
+reallocating the memory in smaller blocks that return to zero.
+After compiling the program and running the following commands,
+a graph of the memory usage of the program can be found in the file
+.IR memusage.png :
 
-.RS 4
+.in +4n
+.nf
+$ \fBmemusage --data=memusage.dat ./a.out\fP
+$ \fBmemusagestat memusage.dat memusage.png\fP
+.fi
+.in
+.SS Program source
+.nf
 #include <stdio.h>
-.RS 0
 #include <stdlib.h>
-.RE
+
-.RS 0
 #define CYCLES 20
-.RE
 
-int main(int argc, char ** argv) {
+int
-         int i, j;
+main(int argc, char *argv[])
-         int *p = NULL;
+{
-         printf("malloc: %d\\n", sizeof(int)*100);
+     int i, j;
-         p = malloc(sizeof(int)*100);
+     int *p;
 
-         for (i = 0; i < CYCLES; i++) {
+     printf("malloc: %zd\\n", sizeof(int) * 100);
-                 if (i < CYCLES/2) j = i; else j--;
+     p = malloc(sizeof(int) * 100);
-                 printf("realloc: %d\\n", sizeof(int)*((j)*50 + 110));
+
-                 p = realloc(p, sizeof(int)*(j*50 + 100));
+     for (i = 0; i < CYCLES; i++) {
-                 printf("realloc: %d\\n", sizeof(int)*((j+1)*150 + 110));
+         if (i < CYCLES / 2)
-                 p = realloc(p, sizeof(int)*((j+1)*150 + 110));
+             j = i;
-         }
+         else
-         free(p);
+             j--;
-         return 0;
+
-.RS 0
+         printf("realloc: %zd\\n", sizeof(int) * (j * 50 + 110));
+         p = realloc(p, sizeof(int) * (j * 50 + 100));
+
+         printf("realloc: %zd\\n", sizeof(int) * ((j+1) * 150 + 110));
+         p = realloc(p, sizeof(int) * ((j + 1) * 150 + 110));
+     }
+
+     free(p);
+     exit(EXIT_SUCCESS);
 }
-.RE
+.fi
-.RE
-
-After compiling and running the following, you can see progress of
-memory usage (memusagestatexample.png):
-
-memusage --data=memusagestatexample.dat ./memusagestatexample
-.RS 0
-memusagestat memusagestatexample.dat memusagestatexample.png
-.RE
-
 .SH BUGS
-For bug reporting instructions, please see:
+To report bugs, see
-<http://www.gnu.org/software/libc/bugs.html>.
+.UR http://www.gnu.org/software/libc/bugs.html
+.UE
 .SH SEE ALSO
-.BR memusage (1)
+.BR memusage (1),
+.BR mtrace (1)