341 lines
13 KiB
Groff
341 lines
13 KiB
Groff
'\"! tbl | mmdoc
|
|
'\"macro stdmacro
|
|
.TH GMEMUSAGE 1
|
|
.SH NAME
|
|
gmemusage \- graphical memory usage viewer
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.ta \w'\f3gmemusage\fP 'u
|
|
\f3gmemusage\fP [ \f3-i\fP \f2interval\fP ]
|
|
[ \f3-m\fP | \f3-p\fP | \f3-r\fP | \f3-s\fP ] [ \f3-u\fP ]
|
|
[ \f3-a\fP \f2aiff-file\fP ] [ \f3-g\fP \f2growth-threshold\fP] [ \f3-y\fP ]
|
|
[ \f3-f\fP \f2font\fP ] [ \f3-v\fP ] [ \f3-n\fP ]
|
|
[ \f3-t\fP \f2thresh\fP ] [ \f3-d\fP \f2delta\fP ]
|
|
[ \f2progs\fP ... ]
|
|
.fi
|
|
.SH DESCRIPTION
|
|
\f2gmemusage\fP is a graphical memory usage viewer. \f2gmemusage\fP
|
|
displays a bar chart depicting the breakdown of memory use, with each
|
|
bar labeled with the name of the program using the memory and the
|
|
number of kilobytes of memory used. If more than one copy of a
|
|
program is running, the number of copies is displayed in parentheses
|
|
after the program name.
|
|
.PP
|
|
In addition, \f2gmemusage\fP will display a breakdown of the regions within
|
|
a program. Clicking on a bar or program name in the main chart will
|
|
replace the main
|
|
chart with a chart for that program, with each region labeled with one
|
|
of \f3Text\fP, \f3Data\fP, \f3Break\fP, \f3Stack\fP, \f3Shmem\fP,
|
|
\f3Physical Device\fP, \f3RW\fP, \f3RO\fP, and (if possible) the base name
|
|
of the file or device corresponding to each region. If gmemusage is
|
|
unable to determine the base name of the file or device for a region
|
|
that does correspond to a file or device, gmemusage will display the
|
|
inode number of the file or device.
|
|
.PP
|
|
The meanings of these labels are as follows:
|
|
.PP
|
|
.TP 10
|
|
.B Text
|
|
This region contains executable instructions. These instructions most
|
|
likely came from an executable program file or a dynamic shared
|
|
object.
|
|
.TP
|
|
.B Data
|
|
This region contains program data. Regions marked \f3Data\fP are
|
|
usually associated with a particular executable program file or a
|
|
dynamic shared object.
|
|
.TP
|
|
.B Break
|
|
Data region that is grown with \f2brk\fP(2). This is the region that
|
|
contains memory allocated by \f2malloc\fP(3C).
|
|
.TP
|
|
.B Stack
|
|
Runtime stack. This is region is used for procedure call frames,
|
|
and can grow if the program makes deeply nested procedure calls or
|
|
calls procedures that allocate large amounts of stack space for
|
|
temporary variables.
|
|
.TP
|
|
.B Shmem
|
|
A System V shared memory region.
|
|
.TP
|
|
.B Physical Device
|
|
Region corresponds to a physical device other than main memory, such
|
|
as a graphics device.
|
|
.TP
|
|
.B RW
|
|
Read/Write data without the Copy on Write bit set. This did not come
|
|
from an executable program file or a dynamic shared object, and could
|
|
be a memory mapped file.
|
|
.TP
|
|
.B RO
|
|
Read only data.
|
|
.TP
|
|
.B Kernel Stack
|
|
Stack used to execute system calls in the kernel.
|
|
.TP
|
|
.B PTEs
|
|
Page table entries.
|
|
.PP
|
|
Clicking on the \f3Irix\fP bar in \f3Physical Memory Breakdown\fP mode
|
|
(see below) causes \f2gmemusage\fP to display a breakdown of the
|
|
memory that it is charging to the operating system. Separate items
|
|
include \f3FS Cache\fP, \f3Buffer Data\fP, \f3Heap\fP, \f3Streams\fP,
|
|
\f3Zone\fP, \f3BSD Networking\fP, \f3Page Frame Data\fP,
|
|
\f3Kernel Tables\fP, \f3Unix Data Space\fP, \f3Unix Code Space\fP,
|
|
\f3Symmon\fP, and \f3Other\fP.
|
|
.PP
|
|
When viewing the breakdown of program memory usage, clicking and
|
|
dragging on the shadow bar will switch the display to another program.
|
|
.PP
|
|
The first time a program is clicked on, \f2gmemusage\fP reads in
|
|
information about executables and libraries on the system while
|
|
displaying a wait
|
|
message. \f2gmemusage\fP keeps this information in its database file
|
|
\f2$HOME/.gmemusage.inodes\fP. if this
|
|
file does not exist or is older than \f2/unix\fP, \f2gmemusage\fP will
|
|
create it, which can take as long as a minute. If the
|
|
database already exists and is newer than \f2/unix\fP, reading it will
|
|
only take a few seconds. See \f3ENVIRONMENT VARIABLES\fP below for
|
|
information on customizing \f2$HOME/.gmemusage.inodes\fP.
|
|
.PP
|
|
\f2gmemusage\fP has four different modes of viewing. The default
|
|
mode, \f3Physical Memory Breakdown\fP, shows the amount of physical
|
|
memory being used by each process, the amount of free memory, and the
|
|
amount of memory being used by Irix.
|
|
The amount of memory charged to each process is calculated by taking
|
|
the pages each process has in memory and pro-rating the sizes
|
|
with the number of processes using each page.
|
|
.PP
|
|
The mode \f3Total Sizes of Process\fP shows the total sizes
|
|
of all the processes in the system. This corresponds to the \f2SZ\fP
|
|
field of \f2ps\fP(1) output.
|
|
.PP
|
|
The mode \f3Resident Sizes of Processes\fP shows the resident sizes of
|
|
all the processes in the system. This corresponds to the \f2RSS\fP
|
|
field of \f2ps\fP(1) output.
|
|
.PP
|
|
The mode \f3Resident Mappings\fP shows the resident sizes of all
|
|
mapped objects in the system. A mapped object can correspond to an
|
|
executable file, a dynamic shared object, a memory mapped file, or a
|
|
region attached to a process by \f2rld\fP(1).
|
|
.PP
|
|
By default, \f2gmemusage\fP only displays programs that are using more
|
|
than 500 kilobytes of memory; programs using less than this are lumped
|
|
together and labeled \f3< 500\fP. This threshold is specifiable on
|
|
the command line and changeable at run time.
|
|
.PP
|
|
Alternatively, a list of programs to monitor can be specified on the
|
|
command line (see below). In this case,
|
|
a bar for each of the programs specified appears (as long as that
|
|
program is running) and any threshold is ignored.
|
|
.PP
|
|
In addition to the four basic viewing modes and the process region
|
|
breakdown, \f2gmemusage\fP cycles through displays of additional
|
|
information when the 'v' key is pressed. This additional information
|
|
is a subdivision of each bar in the chart, with the right portion of each
|
|
bar corresponding to the additional information. Down the right side
|
|
of the window the values corresponding to the right portion of each
|
|
bar are displayed.
|
|
.PP
|
|
The following additional information is available:
|
|
.PP
|
|
.TP 10
|
|
.B Private
|
|
The portion of each bar that is private memory; that is, memory which
|
|
is not being shared. This additional information is available in all
|
|
modes, except when viewing the Irix breakdown.
|
|
.TP
|
|
.B Shared
|
|
The portion of each bar that is shared between more than one process.
|
|
This is calculated by subtracting the \f3Private\fP amount from the
|
|
\f3Physical\fP amount for each bar. \f3Shared\fP is available in all
|
|
modes, except when viewing the Irix breakdown.
|
|
.TP
|
|
.B Physical
|
|
The portion of each bar that is consuming physical memory.
|
|
\f3Physical\fP is available in \f3Resident Sizes of Processes\fP
|
|
and \f3Total Sizes of Processes\fP modes.
|
|
.TP
|
|
.B Resident
|
|
The portion of each bar that is resident in memory (without taking
|
|
sharing into account). \f3Resident\fP is available in \f3Total Sizes
|
|
of Processes\fP mode.
|
|
.PP
|
|
If the environment variable \f3GMEMUSAGESOUND\fP is set to a valid aiff
|
|
file, and \f2playaiff\fP(1) is installed, \f2gmemusage\fP will use
|
|
\f2playaiff\fP(1) to play \f3$GMEMUSAGESOUND\fP when viewing a program's region
|
|
breakdown and the program grows by a thresholded amount. The command
|
|
line option \f3-a\fP can be used as an alternative to the
|
|
environment for specifying a sound file, and the growth threshold can
|
|
be specified on the command line (see below).
|
|
.PP
|
|
\f2gmemusage\fP has the following command line options:
|
|
.PP
|
|
.TP 10
|
|
.BI \-i " interval"
|
|
Update display every \f2interval\fP milliseconds. The default in the
|
|
absence of the \f3-i\fP option is 1000.
|
|
.TP 10
|
|
.BI -m
|
|
Start using \f3Resident Mappings\fP mode.
|
|
.TP 10
|
|
.BI -p
|
|
Start using \f3Physical Memory Breakdown\fP mode. This is the default.
|
|
.TP 10
|
|
.BI -r
|
|
Start using \f3Resident Sizes of Processes\fP mode.
|
|
.TP 10
|
|
.B -s
|
|
Start using \f3Total Sizes of Processes\fP mode.
|
|
.TP 10
|
|
.B -u
|
|
Rebuild the inode database \f2$HOME/.gmemusage.inodes\fP even if it
|
|
isn't older than \f2/unix\fP (see \f3FILES\fP below).
|
|
.TP 10
|
|
.BI \-t " thresh"
|
|
Use \f3thresh\fP kilobytes instead of 500 kilobytes as the starting
|
|
threshold. Programs using less than this amount of memory in a
|
|
particular view are not displayed separately, but rather are lumped
|
|
together in a single bar.
|
|
.TP 10
|
|
.BI \-d " delta"
|
|
Change the threshold by \f2delta\fP kilobytes when the up and down
|
|
arrow keys are pressed (see below). The default is to change the
|
|
threshold by 50 kilobytes.
|
|
.TP 10
|
|
.BI \-a " aiff-file"
|
|
Specify an aiff sound file to be played when viewing a program's
|
|
region breakdown and the program grows by more than a threshold
|
|
amount (see \f3-g\fP option).
|
|
.TP
|
|
.BI \-g " growth-threshold"
|
|
Specify in kilobytes the growth threshold. This is the amount a
|
|
program has to grow before \f2gmemusage\fP will play a sound. The
|
|
default is 12.
|
|
.TP 10
|
|
.B \-y
|
|
Causes gmemusage to print usage information to stdout each interval in
|
|
addition to updating its graphical display.
|
|
.TP
|
|
.BI \-f " font"
|
|
Specifies the font for drawing text.
|
|
.TP
|
|
.B \-v
|
|
Causes gmemusage to use the default visual. By default gmemusage will
|
|
attempt to use a double-buffered TrueColor visual.
|
|
.TP
|
|
.B \-n
|
|
Turns off double-buffering.
|
|
.TP 10
|
|
.BI progs
|
|
Any command line arguments following the arguments described above are
|
|
interpreted as names of programs. If program names are specified,
|
|
\f2gmemusage\fP only displays the memory usage of the programs
|
|
specified, with all other programs lumped together in a bar labeled
|
|
\f3Other\fP. In this case, any threshold or delta is ignored.
|
|
This is useful when one is interested in the behavior of a
|
|
particular program or set of programs, such as when testing for memory
|
|
leaks.
|
|
.SS Runtime controls
|
|
Some of \f2gmemusage\fP's display parameters can be modified at
|
|
runtime. Pressing the 'p' key selects \f3Physical Memory
|
|
Breakdown\fP mode. Pressing the 'r' key selects \f3Resident Sizes of
|
|
Processes\fP mode. Pressing the 's' key selects \f3Total Sizes of
|
|
Processes\fP mode.
|
|
.PP
|
|
Pressing the 'v' key cycles through the available additional
|
|
information for the current mode (see above discussion of additional
|
|
information).
|
|
.PP
|
|
The up arrow key increases the threshold by 50 kilobytes (default)
|
|
or, if the \f3-d\fP option was specified, by \f2delta\fP kilobytes.
|
|
The down arrow key decreases the threshold by the same amount. When
|
|
the threshold is decreased to 0, all programs running are displayed,
|
|
even those that use no memory (such as kernel processes).
|
|
.PP
|
|
In the main view, clicking on a program's bar causes \f2gmemusage\fP
|
|
to display a detailed memory usage chart for that program. In the
|
|
detailed usage view, clicking on the shadow bar switches the program
|
|
being displayed, and clicking outside the shadow bar or pressing the
|
|
space bar returns to the main view.
|
|
.PP
|
|
In any of the detailed usage views (except \f3Resident Mappings\fP),
|
|
pressing the \f3Page Down\fP and \f3Page Up\fP keys navigates you
|
|
through the processes that have been combined under a single program
|
|
name. For example, if you have four \f2xwsh\fP processes running,
|
|
this enables you to see individual memory usage for each \f2xwsh\fP
|
|
process.
|
|
.PP
|
|
At any time, pressing the 't' key causes \f2gmemusage\fP to print
|
|
statistics about the current view to the terminal window. The fields
|
|
in each line are separated by tab characters to simplify the parsing
|
|
of the output by other programs (they are also padded with spaces).
|
|
There are three different types of print outs: \f3All Programs\fP,
|
|
\f3Resident Mappings\fP, and program breakdown. Which gets printed
|
|
depends on the mode \f2gmemusage\fP is in when 't' is pressed.
|
|
.PP
|
|
The 'h' key brings up an on-line help screen, and the space bar
|
|
returns from there to viewing memory. The escape key exits.
|
|
.SH EXAMPLES
|
|
.PP
|
|
.Ex
|
|
gmemusage -p -t 1000 -d 100
|
|
.Ee
|
|
.PP
|
|
Bring up \f2gmemusage\fP in \f3Physical Memory Breakdown\fP
|
|
mode, with programs using 1000 kilobytes or more of memory displayed
|
|
separately in their own bars. The up and down arrow keys will
|
|
increase and decrease the threshold by 100 kilobytes respectively.
|
|
.PP
|
|
.Ex
|
|
gmemusage -r xwsh toolchest 4Dwm Xsgi fm
|
|
.Ee
|
|
.PP
|
|
Bring up \f2gmemusage\fP in \f3Resident Sizes of Processes\fP mode.
|
|
Display bars for \f2xwsh\fP(1), \f2toolchest\fP(1), \f24Dwm\fP(1),
|
|
\f2Xsgi\fP(1), and
|
|
\f2fm\fP(1). All other programs will be combined into a bar labeled
|
|
\f3Other\fP.
|
|
.SH FILES
|
|
.TP \w'$HOME/.gmemusage.inodes\ \ \ \ 'u
|
|
$HOME/.gmemusage.inodes
|
|
Table of files that are likely to correspond to regions mapped
|
|
into processes, along with inode numbers. \f2gmemusage\fP builds this
|
|
table if it doesn't exist or if it is older than \f2/unix\fP or if the
|
|
\f3-u\fP option is supplied, and uses
|
|
it to label the bars when viewing memory breakdown within a process.
|
|
See \f3ENVIRONMENT VARIABLES\fP below for information on altering how
|
|
\f2$HOME/.gmemusage.inodes\fP is built.
|
|
.TP
|
|
/proc
|
|
\f2gmemusage\fP gets memory usage information for processes from the
|
|
\f2/proc\fP file system.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.TP \w'GMEMUSAGESOUND\ \ \ \ 'u
|
|
.B GMEMUSAGESOUND
|
|
If set, \f3$GMEMUSAGESOUND\fP is used as an aiff file to be played by
|
|
\f2playaiff\fP(1) when viewing a process's region breakdown and the
|
|
process grows (see above).
|
|
.TP
|
|
.B GMEMUSAGEPATH
|
|
Colon separated list of directories to recursively search when
|
|
building the inode database, \f2$HOME/.gmemusage.inodes\fP. If
|
|
\f3GMEMUSAGEPATH\fP is not found in the environment, \f2gmemusage\fP uses
|
|
the following default path:
|
|
.PP
|
|
.Ex
|
|
/usr/lib:/usr/lib32:/usr/lib64:
|
|
/usr/local:/usr/sysadm:/var/ns/lib:
|
|
/lib:/lib32:/lib64:/usr/gfx
|
|
.Ee
|
|
.SH BUGS
|
|
The totals displayed for the breakdown of a program's regions do not
|
|
always add up exactly to the amount of memory in the main view. In
|
|
\f3Physical Memory\fP mode, this discrepancy is due to rounding error.
|
|
In \f3Total Size\fP mode, this is often due to the inclusion of
|
|
physical devices in the breakdown. The \f3Resident Size\fP
|
|
discrepancies are currently being studied.
|
|
.SH SEE ALSO
|
|
\f2ps\fP(1), \f2top\fP(1), \f2gr_top\f(1), \f2osview\fP(1),
|
|
\f2gr_osview\fP(1), \f2proc\fP(4).
|