GMEMUSAGE(1) GMEMUSAGE(1)
NAME
gmemusage - graphical memory usage viewer
SYNOPSIS
gmemusage [ -i interval ]
[ -m | -p | -r | -s ] [ -u ]
[ -a aiff-file ] [ -g growth-threshhold ]
[ -t thresh ] [ -d delta ]
[ progs ... ]
DESCRIPTION
gmemusage is a graphical memory usage viewer. gmemusage 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.
In addition, gmemusage 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 Text, Data, Break, Stack, Shmem, Physical Device, RW,
RO, 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.
The meanings of these labels are as follows:
Text This region contains executable instructions. These
instructions most likely came from an executable program file
or a dynamic shared object.
Data This region contains program data. Regions marked Data are
usually associated with a particular executable program file or
a dynamic shared object.
Break Data region that is grown with brk(2). This is the region that
contains memory allocated by malloc(3C).
Stack Runtime stack. This is region is used for procecure 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.
Shmem A System V shared memory region.
Physical Device
Region corresponds to a physical device other than main memory,
such as a graphics device.
Page 1
GMEMUSAGE(1) GMEMUSAGE(1)
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.
RO Read only data.
Kernel Stack
Stack used to execute system calls in the kernel.
PTEs Page table entries.
Clicking on the Irix bar in Physical Memory Breakdown mode (see below)
causes gmemusage to display a breakdown of the memory that it is charging
to the operating system. Separate items include FS Cache, Buffer Data,
Heap, Streams, Zone, BSD Networking, Page Frame Data, Kernel Tables, Unix
Data Space, Unix Code Space, Symmon, and Other.
When viewing the breakdown of program memory usage, clicking and dragging
on the shadow bar will switch the display to another program.
The first time a program is clicked on, gmemusage reads in information
about executables and libraries on the system while displaying a wait
message. gmemusage keeps this information in its database file
$HOME/.gmemusage.inodes. if this file does not exist or is older than
/unix, gmemusage will create it, which can take as long as a minute. If
the database already exists and is newer than /unix, reading it will only
take a few seconds. See ENVIRONMENT VARIABLES below for information on
customizing $HOME/.gmemusage.inodes.
gmemusage has four different modes of viewing. The default mode,
Physical Memory Breakdown, 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.
The mode Total Sizes of Process shows the the total sizes of all the
processes in the system. This corresponds to the SZ field of ps(1)
output.
The mode Resident Sizes of Processes shows the resident sizes of all the
processes in the system. This corresponds to the RSS field of ps(1)
output.
The mode Resident Mappings 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 rld(1).
By default, gmemusage only displays programs that are using more than 500
kilobytes of memory; programs using less than this are lumped together
and labeled < 500. This threshhold is specifiable on the command line
Page 2
GMEMUSAGE(1) GMEMUSAGE(1)
and changeable at run time.
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 threshhold
is ignored.
In addition to the four basic viewing modes and the process region
breakdown, gmemusage 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.
The following additional information is available:
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.
Shared The portion of each bar that is shared between more than one
process. This is calculated by subtracting the Private amount
from the Physical amount for each bar. Shared is available in
all modes, except when viewing the Irix breakdown.
Physical The portion of each bar that is consuming physical memory.
Physical is available in Resident Sizes of Processes and and
Total Sizes of Processes modes.
Resident The portion of each bar that is resident in memory (without
taking sharing into acount). Resident is available in Total
Sizes of Processes mode.
If the environment variable GMEMUSAGESOUND is set to a valid aiff file,
and playaiff(1) is installed, gmemusage will use playaiff(1) to play
$GMEMUSAGESOUND when viewing a program's region breakdown and the program
grows by a threshholded amount. The command line option -a can be used
as an alternative to the environment for specifying a sound file, and the
growth threshhold can be specified on the command line (see below).
gmemusage has the following command line options:
-iinterval
Update display every interval milliseconds. The default in the
absence of the -i option is 1000.
-m Start using Resident Mappings mode.
-p Start using Physical Memory Breakdown mode. This is the
default.
Page 3
GMEMUSAGE(1) GMEMUSAGE(1)
-r Start using Resident Sizes of Processes mode.
-s Start using Total Sizes of Processes mode.
-u Rebuild the inode database $HOME/.gmemusage.inodes even if it
isn't older than /unix (see FILES below).
-tthresh Use thresh kilobytes instead of 500 kilobytes as the starting
threshhold. 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.
-ddelta Change the threshhold by delta kilobytes when the up and down
arrow keys are pressed (see below). The default is to change
the threshhold by 50 kilobytes.
-aaiff-file
Specify an aiff sound file to be played when viewing a
program's region breakdown and the program grows by more than a
threshhold amount (see -g option).
-ggrowth-threshhold
Specify in kilobytes the growth threshhold. This is the amount
a program has to grow before gmemusage will play a sound. The
default is 12.
progs Any command line arguments following the arguments described
above are interpreted as names of programs. If program names
are specified, gmemusage only displays the memory usage of the
programs specified, with all other programs lumped together in
a bar labeled Other. In this case, any threshhold 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.
Runtime controls
Some of gmemusage's display parameters can be modified at runtime.
Pressing the 'p' key selects Physical Memory Breakdown mode. Pressing
the 'r' key selects Resident Sizes of Processes mode. Pressing the 's'
key selects Total Sizes of Processes mode.
Pressing the 'v' key cycles through the available additional information
for the current mode (see above discussion of additional information).
The up arrow key increases the threshhold by 50 kilobytes (default) or,
if the -d option was specified, by delta kilobytes. The down arrow key
decreases the threshhold by the same amount. When the threshhold is
decreased to 0, all progams running are displayed, even those that use no
memory (such as kernel processes).
Page 4
GMEMUSAGE(1) GMEMUSAGE(1)
In the main view, clicking on a program's bar causes gmemusage 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.
In any of the detailed usage views (except Resident Mappings), pressing
the Page Down and Page Up keys navigates you through the processes that
have been combined under a single program name. For example, if you have
four xwsh processes running, this enables you to see individual memory
usage for eah xwsh process.
At any time, pressing the 't' key causes gmemusage 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: All Programs, Resident Mappings, and
program breakdown. Which gets printed depends on the mode gmemusage is
in when 't' is pressed.
The 'h' key brings up an on-line help screen, and the space bar returns
from there to viewing memory. The escape key exits.
EXAMPLES
gmemusage -p -t 1000 -d 100
Bring up gmemusage in Physical Memory Breakdown 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 threshhold by
100 kilobytes respectively.
gmemusage -r xwsh toolchest 4Dwm Xsgi fm
Bring up gmemusage in Resident Sizes of Processes mode. Display bars for
xwsh(1), toolchest(1), 4Dwm(1), Xsgi(1), and fm(1). All other programs
will be combined into a bar labeled Other.
FILES
$HOME/.gmemusage.inodes Table of files that are likely to correspond
to regions mapped into processes, along with
inode numbers. gmemusage builds this table if
it doesn't exist or if it is older than /unix
or if the -u option is supplied, and uses it
to label the bars when viewing memory
breakdown within a process. See ENVIRONMENT
VARIABLES below for information on altering
how $HOME/.gmemusage.inodes is built.
Page 5
GMEMUSAGE(1) GMEMUSAGE(1)
/proc gmemusage gets memory usage information for
processes from the /proc file system.
ENVIRONMENT VARIABLES
GMEMUSAGESOUND If set, $GMEMUSAGESOUND is used as an aiff file to be
played by playaiff(1) when viewing a process's region
breakdown and the process grows (see above).
GMEMUSAGEPATH Colon separated list of directories to recursively
search when building the inode database,
$HOME/.gmemusage.inodes. If GMEMUSAGEPATH is not found
in the environment, gmemusage uses the following
default path:
/usr/lib:/usr/lib32:/usr/lib64:
/usr/local:/usr/sysadm:/var/ns/lib:
/lib:/lib32:/lib64:/usr/gfx
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
Physical Memory mode, this discrepancy is due to rounding error. In
Total Size mode, this is often due to the inclusion of physical devices
in the breakdown. The Resident Size discrepancies are currently being
studied.
SEE ALSO
ps(1), top(1), gr_top, osview(1), gr_osview(1), proc(4).
Page 6