From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jan Chaloupka Subject: Re: For review: memusage(1) man page Date: Tue, 22 Jul 2014 08:30:47 +0200 Message-ID: <53CE0517.2040005@redhat.com> References: <53C8E244.2080901@redhat.com> <53CE0144.7050405@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <53CE0144.7050405-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> Sender: linux-man-owner-u79uwXL29TY76Z2rM5mHXA@public.gmane.org To: "Michael Kerrisk (man-pages)" Cc: linux-man-u79uwXL29TY76Z2rM5mHXA@public.gmane.org, libc-alpha-9JcytcrH/bA+uJoB2kUjGw@public.gmane.org, myllynen-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org, drepper-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org, Peter Schiffer List-Id: linux-man@vger.kernel.org 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-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org) >> .\" >> .\" %%%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 >> .\" . >> .\" %%%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: >> . >> .SH SEE ALSO >> .BR memusagestat (1), >> .BR ld.so (8) >> > -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org More majordomo info at http://vger.kernel.org/majordomo-info.html