HOWTO use gdb to debug program errors

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

The GNU Debugger (gdb) can be used with ns-3 and Waf to debug program errors. There are several tutorials online (search for 'gdb tutorial' in a search engine) that explain how to use gdb in general.

This HOWTO is related to another HOWTO that describes how to invoke the valgrind tool to find memory leaks.

running gdb with Waf

Waf supports a --command-template argument that allows users to launch gdb and run the programs from there.

 ./waf --command-template="gdb %s" --run <program-name>

An example using the third tutorial example, running it first to ask that the help message be printed out, and then running it with an illegal argument:

 ./waf --command-template="gdb %s" --run third
 (gdb) r --help
 (gdb) run --nWifi=0
 ...
 Program received signal SIGSEGV, Segmentation fault.
 0x0000000000413ac9 in ns3::PeekPointer<ns3::Node> (p=...) at ./ns3/ptr.h:282
 282	  return p.m_ptr;
 (gdb) 

To debug an individual test suite, use the test-runner program:

 ./waf --command-template="gdb %s" --run test-runner
 (gdb) run --suite=csma-system

running gdb with Waf, redirecting all output to a file

Sometimes a program will generate a lot of output to stdout and stderr, which may get in the way of interactively using the gdb prompt. It is possible to redirect program output to a file, while interacting with the gdb prompt. Here is a trivial example.

 ./waf --command-template="gdb %s" --run third
 (gdb) run --help > output.txt 2>&1

An example of how to run an individual test suite this way, launching gdb from the command line:

 ./waf --run test-runner --command-template="gdb -ex 'run --suite=csma-system > csma-output.txt 2>&1' --args %s"