


Using Debugging Mode
Using Debugging Mode
This section explains how to debug a program's memory management with Sun WorkShop Memory Monitor.
Quick Reference for Debugging Mode
To use Sun WorkShop Memory Monitor's debugging tools:
|
Using Debugging Mode
|
1.
|
Add libgc_dbg.a (or libgc_dbg.so, if supported) to your program's project or makefile.
|
2.
|
Build your program with debug information.
|
3.
|
Run your program.
|
4.
|
Start the GC Monitor daemon by running gcmonitor. This will serve the Sun WorkShop Memory Monitor web pages.
|
5.
|
In your web browser, browse your machine's Sun WorkShop Memory Monitor home page at http://127.0.0.1:2660/. If your browser is running on a different machine as your program, browse http://<machine name>:2660.
|
6.
|
Click on the select program tab and select your program.
|
7.
|
View debugging reports in the browser
|
Instructions for Debugging Mode
Sun WorkShop Memory Monitor has a debugging mode which will automatically report on memory management errors. To use debugging mode, follow these steps:
- Add libgc_dbg.a (or libgc_dbg.so) to your program's project or makefile.
- Build your program with debug information. Sun WorkShop Memory Monitor understands a wide variety of debug formats, and can give you some information even when debug info is not available.
- Run your program.
- Start the GC Monitor daemon by running gcmonitor. For arguments, see see "Using the GC Monitor") This will serve the Sun WorkShop Memory Monitor web pages.
- In your web browser, browse the debugging web pages at http://127.0.0.1:2660/. If your browser is running on a different machine as your program, browse http://<machine name>:2660. If the debugging home page does not appear, see the notes below.
- Click on the select program tab and select your program.
- Click on other tabs to get reports on your program, such as leak reports and heap profiling reports. You can view the online documentation or read "The GC Monitor Web Pages" to understand the reports.
Notes:
- If you can't browse your computer's debugging home page, go to "Troubleshooting the GC Monitor."
- Sun WorkShop Memory Monitor comes with a special tool called the Memory Debugger, which allows you to debug without explicitly linking to the debugging library. It lets you debug your program and use the GC Monitor in one easy step, without relinking or rebuilding, even if you don't have the source code. For more information, read "The Memory Debugger".
- Sun WorkShop Memory Monitor always reclaims leaked memory, even in debugging mode. This protects you from memory leaks throughout development.
- Sun WorkShop Memory Monitor can also automatically protect you against premature frees. At the start of your program, call gcFixPrematureFrees(), which is defined in gct.h. You can also experiment with this feature from the web user interface, as described in "Configuring from the Web Interface." Warning: Although Sun WorkShop Memory Monitor can protect against premature frees, it does not report on them. See "Automatically Fixing Premature Frees" for more information.
- Sun WorkShop Memory Monitor writes a log file of the debugging session named gc.log. You can also view this file in the log file tab of the web interface.
- Sun WorkShop Memory Monitor detects double frees and memory overwrites and reports them to the log file, gc.log. You can view this file from the log file tab of the web interface or by opening the file directly.
- Although Sun WorkShop Memory Monitor is highly reliable, there are some restrictions on its use. Look at "Usage Restrictions" to see these restrictions. Look at "Troubleshooting Sun WorkShop Memory Monitor" if you suspect Sun WorkShop Memory Monitor is not operating properly in your program.
Using the GC Monitor
The GC Monitor is the web interface to Sun WorkShop Memory Monitor. With the web interface, you can:
- Debug your program's memory management from within your browser.
- Debug programs remotely in your web browser.
- Sort, filter, and summarize leak information at the touch of a button.
- Sort, filter, and summarize allocation and heap statistics, allowing you to see at a glance where and how your program is using memory.
- View the log file online.
- View the documentation on-line.
- Submit technical support issues on-line.
- Go to the Sun Microsystems website for additional tips, search the knowledge base, etc.
Quick Reference for the GC Monitor
To use Sun WorkShop Memory Monitor's debugging tools:
|
Using the GC Monitor
|
1.
|
Verify that the GC Monitor daemon is running. If not, run gcmonitor (see arguments below).
|
2.
|
In your web browser, browse your machine's debugging home page at http://127.0.0.1:2660/. If your browser is running on a different machine as your program, browse http://<machine name>:2660.
|
3.
|
View debugging reports in the browser
|
How to use the GC Monitor
To use the GC monitor, follow these steps:
- Start the GC Monitor daemon by running gcmonitor which is located in the directory gc/gcmonitor/. You can modify its behavior with the following arguments:
Usage: gcmonitor [[-h] [-p port] [-v] [-m mon-path] [-r]]*
-h: prints how to use this command
-p: sets port of http server (default port is 2660)
-v: sets verbose mode
-m: looks for monitor files in directory mon-path (default is /tmp)
-r: read-only. Monitor files cannot be deleted.
- In your web browser, browse your machine's debugging home page at http://127.0.0.1:2660/. If your browser is running on a different machine as your program, browse http://<machine name>:2660, where <machine name> is the name of the machine where the debugged program is being run. If the home page does not appear follow the instructions in "Troubleshooting the GC Monitor."
A Note on Security
The Sun Workshop Memory Monitor communicates debug information about your
application from the gcmonitor program over a well-known TCP/IP port (2660 by
default) to the Web GUI in your browser. This debug information includes
function names, file names, line numbers, module names and heap statistics.
This information is not encrypted and users who are concerned about the
security of this information should use a different port to communicate
between browser and gcmonitor. This is done by setting the -p parameter when
starting the gcmonitor program:
gcmonitor -p NNNNN
where NNNNN is any unused TCP/IP port. When viewing the debug information
in your browser, in the address field enter:
http://:NNNNN
where NNNNN corresponds to the -p parameter used in starting gcmonitor on
the machine . For more information about gcmonitor, see the
man page entry on gcmonitor.



