HOWTO use gdb to debug program errors

From Nsnam
Jump to: navigation, search

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 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.

One example of such tutorials is part of the Red Hat user guide.

This HOWTO is related to another HOWTO that explains how to use the insight tool (a graphical front-end for gdb) to debug segmentation faults.

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

running gdb directly

gdb can be invoked on a program executable in the normal way (gdb <program-name>), and to do this with ns-3, it is easiest to use the ns3 shell (to set the library paths correctly). We demonstrate with an example of the third tutorial example.

 ./ns3 shell
 cd build/examples/tutorial
 gdb ns3-dev-third-debug
 Reading symbols from ns3-dev-third-debug...done.
 (gdb) 

At this point, one can set breakpoints in the ns-3 libraries, or run the program. We can run it with the --help argument to print out the program usage:

 (gdb) r --help

Or we can deliberately cause a program error by running with an illegal argument

 (gdb) r --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 run a test-suite through gdb, use the test-runner program, such as:

 ./ns3 shell
 cd build/utils/
 gdb ns3-dev-test-runner-debug
 (gdb) r --suite=csma-system
 (gdb) quit

running gdb with ns3 script

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

 ./ns3 run --gdb <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:

 ./ns3 run --gdb third
 (gdb) r --help
 (gdb) run --nWifi=0
 ...
 Program received signal SIGSEGV, Segmentation fault.
 ns3::NodeContainer::Get (this=this@entry=0x7fffffffd980, i=4294967295)
    at ../src/network/helper/node-container.cc:95
 95	  return m_nodes[i];
 (gdb)

The program execution is now stopped at the point of the segmentation fault. For a segmentation fault, this often means that the program is trying to access an object from a pointer, but the pointer is not valid. You can check here on the value of 'i' and 'm_nodes[i]' by using the gdb print (abbreviated as 'p'):

 (gdb) p i
 $1 = 4294967295

You can see how you got to this point by using the 'backtrace' (abbreviated as 'bt'), as follows:

 (gdb) bt
 #0  ns3::NodeContainer::Get(unsigned int) const
   (this=this@entry=0x7fffffffd980, i=4294967295)
   at ../src/network/helper/node-container.cc:95
 #1  0x000055555555e13e in main(int, char**)
   (argc=<optimized out>, argv=<optimized out>)
   at ../examples/tutorial/third.cc:165

You can step back up through the call stack to inspect the program state, using the 'up' command:

 (gdb) up
 #1  0x000055555555e13e in main (argc=<optimized out>, argv=<optimized out>)
   at ../examples/tutorial/third.cc:165
 165	  ApplicationContainer clientApps =

This tells me that line 165 of third.cc was the trigger. Let's look at that code:

 ApplicationContainer clientApps =
   echoClient.Install (wifiStaNodes.Get (nWifi - 1));

Now it should be obvious why the program segfaulted, and why the value of i above was invalid.

Notice that some of the values above say 'optimized out'. This is because I was debugging on a program that was compiled with some optimizations. To really see in detail what is going on, build ns-3 in 'debug' mode before running gdb.

To debug an individual test suite, use the test-runner program, such as the following example of the 'csma-system' test suite:

 ./ns3 run --gdb test-runner
 (gdb) run --suite=csma-system

running gdb with ns3, 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.

 ./ns3 run --gdb 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:

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

saving breakpoints across sessions

As of gdb 7.2, breakpoints can be saved to a file and reloaded for a separate session.

For example:

 (gdb) info break
 Num     Type           Disp Enb Address    What
 1       breakpoint     keep y   <PENDING>  random-variable-stream.cc:175
 2       breakpoint     keep y   <PENDING>  random-variable-stream.cc:186

to save them to a file called 'breaks':

 (gdb) save breakpoints breaks

Later, one can retrieve them as follows.

 (gdb) source breaks

In ns-3 with shared libraries, one may get this error:

 (gdb) source breaks
 No source file named random-variable-stream.cc.
 Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]
 No source file named random-variable-stream.cc.
 Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]

to work around this, use the command 'set breakpoints pending on' before sourcing the file:

 (gdb) set breakpoint pending on
 (gdb) source breaks
 No source file named random-variable-stream.cc.
 Breakpoint 1 (random-variable-stream.cc:175) pending.
 No source file named random-variable-stream.cc.
 Breakpoint 2 (random-variable-stream.cc:186) pending.
 (gdb) info break
 Num     Type           Disp Enb Address    What
 1       breakpoint     keep y   <PENDING>  random-variable-stream.cc:175
 2       breakpoint     keep y   <PENDING>  random-variable-stream.cc:186