Re: For review: memusage(1) man page

["Michael Kerrisk (man-pages)" <mtk dot manpages at gmail dot com>]

Jan,

On 07/18/2014 11:00 AM, Jan Chaloupka wrote:
> Hi,
> 
> memusage command is no documented. My collegue (95%) and I (5%) have 
> written a man page for it. All informations come from inspecting the 
> script code. This is the first script, others are memusagestat (1) and 
> mtrace(1).
> 
> Feel free to comment or ask any question.

Thanks for these submissions. It will take me a while to get to
looking at them more closely. My time is very limited at the moment.

I'll eventually have some other comments, but it strikes me that
this page could use a small example, if it is feasible to create
one. Would you (or Peter) be willing to have a go at that?

Cheers,

Michael


> Thank you
> Jan
> 
> .\" 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 MEMUSAGE 1 2013-04-10 "GNU glibc 2.18" "Memory diagnostic tools"
> .SH NAME
> memusage \- profile memory usage of a program
> .SH SYNOPSIS
> .BR memusage " [\fIOPTION\fR]... \fIPROGRAM\fR [\fIPROGRAMOPTION\fR]..."
> .SH DESCRIPTION
> .B memusage
> is a bash script which can profile memory usage of a program. It preloads
> .B libmemusage.so
> library to the user's environment using
> .B LD_PRELOAD
> environment variable. The
> .B libmemusage.so
> library traces memory allocation by intercepting calls to
> .BR malloc (3),
> .BR free (3),
> .BR realloc (3)
> and various other calls.
> .PP
> .B memusage
> can output text representation of the collected data, or it can use
> .BR memusagestat (1)
> utility (see
> .B -p
> option)
> to create a PNG file containing graphical representation
> of the collected data.
> .TP
> List of monitored functions:
> .RS
> .BI "void *malloc(size_t " "size" );
> .RE
> .RS
> .BI "void *calloc(size_t " "nmemb" ", size_t " "size" );
> .RE
> .RS
> .BI "void *realloc(void " "*ptr" ", size_t "  "size" );
> .RE
> .RS
> .BI "void *mmap(void " "*addr" ", size_t " "length" ", int " "prot",
> .BI "int " "flags" ", int " "fd" ", off_t " "offset");
> .RE
> .RS
> .BI "void *mremap(void " "*old_address" ", size_t " "old_size",
> .BI "size_t " "new_size" ", int " "flags",
> .BI "... /* void " "*new_address" " */);"
> .RE
> .TP
> Description of a memory usage summary:
> .RE
> \fBheap total\fR:
> .RS
> Sum of \fIsize\fR arguments of all malloc calls,
> sum of all product of arguments (\fInmemb\fR*\fIsize\fR) of calloc call
> and sum of \fIlength\fR arguments of mmap calls.
> In a case of realloc, respectively mremap, if a new size of an original 
> malloc,
> respectively mremap call is bigger than an old one,
> sum of all such differences (new size - old size) is added.
> .RE
> \fBheap peak\fR:
> .RS
> Maximum of all \fIsize\fR arguments of malloc,
> all products of \fInmemb\fR*\fIsize\fR of calloc,
> all \fIsize\fR arguments of realloc, \fIlength\fR arguments of mmap and
> \fInew_size\fR arguments of mremap.
> .RE
> \fBstack peak\fR:
> .RS
> Before the first call to any monitored function,
> stack pointer address (base stack pointer) is saved.
> After each function call, actual stack pointer address is read and
> the difference between the base stack pointer computed.
> Maximum of these differences is then the stack peak.
> .RE
> 
> If a realloc function is called on a mallocced memory with a new size being
> smaller than an old one, total memory of realloc cell is not updated.
> This can cause sum of all cells (excluding free) of total memory being
> greater than free cell.
> .SH OPTIONS
> .TP
> .BI \-n\  name \fR,\ \fB\-\-progname= name
> Name of the program file to profile.
> .TP
> .BI \-p\  file \fR,\ \fB\-\-png= file
> Generate PNG graphic and store it in the file.
> .TP
> .BI \-d\  file \fR,\ \fB\-\-data= file
> Generate binary data file and store it in the file.
> .TP
> .BI \-u\fR,\ \fB\-\-unbuffered
> Do not buffer output.
> .TP
> .BI \-b\  size \fR,\ \fB\-\-buffer= size
> Collect size entries before writing them out.
> .TP
> .BI \fB\-\-no-timer
> Do not collect additional information through timer.
> .TP
> .BI \-m\fR,\ \fB\-\-mmap
> Also trace mmap and friends.
> .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.
> .TP
> The following options only apply when generating graphical output:
> .TP
> .BI \-t\fR,\ \fB\-\-time\-based
> Make graph linear in time.
> .TP
> .BI \-T\fR,\ \fB\-\-total
> Also draw graph of total memory use.
> .TP
> .BI \fB\-\-title= name
> Use the name as a title of the graph.
> .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.
> .SH EXIT STATUS
> Exit status is equal to the exit status of profiled program.
> .SH BUGS
> For bug reporting instructions, please see:
> <http://www.gnu.org/software/libc/bugs.html>.
> .SH SEE ALSO
> .BR memusagestat (1),
> .BR ld.so (8)
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/