For review: memusage(1) man page

[Jan Chaloupka]

On 07/22/2014 08:14 AM, Michael Kerrisk (man-pages) wrote:
> 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.

Thank you for review.

> 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?

I will create one.

> 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)
>>
>