Re: For review: memusage(1) man page

[Jan Chaloupka <jchaloup at redhat dot com>]

Adding example with small C code to demonstrate progress of memory usage

.\" Copyright (c) 2013, Peter Schiffer (pschiffe@redhat.com)
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" 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"
.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 
data.
Red line in the graph shows the heap usage (allocated memory),
green line shows the stack usage,
x-scale number of memory handling functions calls or time (\fB-t\fR option).
.I DATAFILE
is a binary data file generated by
.BR memusage (1)
utility with
.B -d
option.
.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.
.TP
.BI \-t\fR,\ \fB\-\-time
Generate output linear to time
(default is linear to number of function calls).
.TP
.BI \-T\fR,\ \fB\-\-total
Also draw graph for total memory consumption.
.TP
.BI \-x\  size \fR,\ \fB\-\-x-size= size
Make graphic size pixels wide.
.TP
.BI \-y\  size \fR,\ \fB\-\-y\-size= size
Make graphic size pixels high.
.TP
.BI \-?\fR,\ \fB\-\-help
Print help 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
Here is a simple program \fImemusagestatexample.c\fR simulating increase 
and decrease of memory usage:

.RS 4
#include <stdio.h>
.RS 0
#include <stdlib.h>
.RE
.RS 0
#define CYCLES 20
.RE

int main(int argc, char ** argv) {
        int i, j;
        int *p = NULL;
        printf("malloc: %d\\n", sizeof(int)*100);
        p = malloc(sizeof(int)*100);

        for (i = 0; i < CYCLES; i++) {
                if (i < CYCLES/2) j = i; else j--;
                printf("realloc: %d\\n", sizeof(int)*((j)*50 + 110));
                p = realloc(p, sizeof(int)*(j*50 + 100));
                printf("realloc: %d\\n", sizeof(int)*((j+1)*150 + 110));
                p = realloc(p, sizeof(int)*((j+1)*150 + 110));
        }
        free(p);
        return 0;
.RS 0
}
.RE
.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:
<http://www.gnu.org/software/libc/bugs.html>.
.SH SEE ALSO
.BR memusage (1)