Using the GNU debugger (GDB)

Much of the content of this page was extracted from John W. Clark's GDB page. It in turn is a summary of the GNU GDB info manual, which can be accessed by typing

info gdb



at the Linux command prompt. 


Introduction


The purpose of a debugger such as GDB is to allow you to see what is going on
"inside" another program while it executes--or what another program was doing
at the moment it crashed. 



GDB can do five main kinds of things (plus other things in support of these) 
to help you catch bugs in the act: 


  Start your program, specifying anything that might affect its behavior. 
  
Load a core file generated by your program when it crashed.
  
Make your program stop on specified conditions. 
  
Examine what has happened, when your program has stopped. 
  
Change things in your program, so you can experiment with correcting the 
      effects of one bug and go on to learn about another.



In order to debug a program effectively, you need to generate debugging
information when you compile it. This debugging information is stored in the
object file; it describes the data type of each variable or function and the
correspondence between source line numbers and addresses in the executable
code.  To request debugging information, specify the `-g' option when you run
the compiler; for instance,


  

    gcc -g -o tcp_card_dealer tcp_card_dealer.c -L. -lmy_net
  





GDB Quickstart

The following is a list of common GDB operations which you might often use:


  quit 
  
Exit gdb when you've had all the fun you can take...

  
help 
  
Access gdb's online help files.


Stopping Execution


  break 
  
A breakpoint makes your program stop whenever a certain point in 
  the program is reached.  For each breakpoint, you can add conditions to
  control in finer detail whether your program stops. You can set breakpoints
  with the `break' command and its variants to specify the place where your
  program should stop by line number, function name or exact address in the
  program.

  
    break FUNCTION 
    
Set a breakpoint at entry to function FUNCTION. 
    
break LINENUM 
    
Set a breakpoint at line LINENUM in the current source file. 
    
break FILENAME:LINENUM 
    
Set a breakpoint at line LINENUM in source file FILENAME. 
    
break FILENAME:FUNCTION 
    
Set a breakpoint at entry to function FUNCTION found in file FILENAME. 
    
break ... if COND 
    
Set a breakpoint with condition COND; evaluate the expression COND each 
    time the breakpoint is reached, and stop only if the value is nonzero--that 
    is, if COND evaluates as true. ... stands for one of the possible arguments 
    described above (or no argument) specifying where to break.
  

  
watch 
  
You can use a watchpoint to stop execution whenever the value of an 
  expression changes, without having to predict a particular place where this 
  may happen. 

  
    watch EXPR 
    
Set a watchpoint for an expression. GDB will break when EXPR is written 
    into by the program and its value changes. 
  

  
info 
  
Print a table of all breakpoints and watchpoints set and not deleted,
  with the following columns for each breakpoint:
  
  
    info breakpoints [N]

          info break [N]

          info watchpoints [N]
  
    (gdb) info break
  Num Type           Disp Enb Address    What
  1   breakpoint     keep y   0x080483d4 in main at abc.c:5
          breakpoint already hit 1 time 

  
clear 
  
Delete any breakpoints at the next instruction to be executed in the 
  selected stack frame. When the innermost frame is selected, this is a good way 
  to delete a breakpoint where your program just stopped. 
  
    clear FUNCTION
clear FILENAME:FUNCTION 
    
Delete any breakpoints set at entry to the function FUNCTION. 
    
clear LINENUM
clear FILENAME:LINENUM 
    
Delete any breakpoints set at or within the code of the specified line. 
    
  

  
delete [breakpoints] [BNUMS...] 
  
Delete the breakpoints or watchpoints of the numbers specified as 
  arguments. If no argument is specified, delete all breakpoints (GDB asks 
  confirmation, unless you have `set confirm off'). You can abbreviate this 
  command as `d'. 


Running/Resuming Execution


  run 
  
Use the `run' command to start your program under GDB. You must first 
  specify the program name with an argument to GDB, or by using the `file' or 
  `exec-file' command. 

  
step 
  
Continue running your program until control reaches a different source 
  line, then stop it and return control to GDB. This command is abbreviated 
  s. 
  
    step [COUNT] (shorthand s) 
    
Continue running as in `step', but do so COUNT times. If a breakpoint is 
    reached, or a signal not related to stepping occurs before COUNT steps, 
    stepping stops right away. 
  
 
  
next [COUNT] (shorthand n) 
  
Continue to the next source line in the current (innermost) stack frame. 
  This is similar to `step', but function calls that appear within the line of 
  code are executed without stopping. Execution stops when control reaches a 
  different line of code at the original stack level that was executing when you 
  gave the `next' command. This command is abbreviated `n'. 

  
continue [IGNORE-COUNT] (shorthand c) 
  
Resume program execution, at the address where your program last stopped; 
  any breakpoints set at that address are bypassed. The optional argument 
  IGNORE-COUNT allows you to specify a further number of times to ignore a 
  breakpoint at this location. 

  
finish 
  
Continue running until just after function in the selected stack frame 
  returns. Print the returned value (if any).

  
kill 
  
Terminate the process that's running in the debugger.  This won't stop
  the debugger, just end debugging the executable.  You can restart it with the
  run command.


Examining the Data and Source Code


  print [EXP] (shorthand p) 
  
EXP is an expression (in the source language). By default the value of EXP 
  is printed in a format appropriate to its data type; If you omit EXP, GDB 
  displays the last value again. 

  
display EXP (shorthand disp) 
  
Add the expression EXP to the list of expressions to display each time 
  your program stops. `display' does not repeat if you press RET again after 
  using it. 

  
set VAR=VALUE
  
Assign a new value to the variable VAR.  For example,
      set width=47

  
list (shorthand l) 
  
To print lines from a source file, use the `list' command (abbreviated 
  `l'). By default, ten lines are printed. There are several ways to specify 
  what part of the file you want to print. 

  Here are the forms of the `list' command most commonly used: 
  

    list LINENUM 
    
Print lines centered around line number LINENUM in the current source 
    file. 

    
list FUNCTION 
    
Print lines centered around the beginning of function FUNCTION. 

    
list 
    
Print more lines. If the last lines printed were printed with a `list' 
    command, this prints lines following the last lines printed; however, if the 
    last line printed was a solitary line printed as part of displaying a stack 
    frame (*note Examining the Stack: Stack.), this prints lines centered around 
    that line. 

    
list - 
    
Print lines just before the lines last printed. 
  
  


Examining the Stack


When your program has stopped, the first thing you need to know is where it
stopped and how it got there. 


Each time your program performs a function call, information about the call 
is generated. That information includes the location of the call in your 
program, the arguments of the call, and the local variables of the function 
being called. The information is saved in a block of data called a "stack 
frame". The stack frames are allocated in a region of memory called the "call 
stack". 



  backtrace (shorthand bt, where) 
  
Print a backtrace of the entire stack: one line per frame for all frames 
  in the stack.
  
  
up
  
Moves up to the next stack frame, so you can print the local variables
  that were in scope within that frame.


Examining a Core File


If your program crashes (due to a segmentation fault, for example) and "dumps
core" (produces a core file), you can load that file into gdb and do many of
the same operations you can do by starting the program in the debugger and
running it until it crashes.  These operations include looking at the stack
trace, moving up through the trace, examining the values in variables, and
printing source code lines.



To examine a core file, start gdb normally, specifying the name of the
executable that generated the core.  Then enter

  

    core <core_file_name>
  


to load the core.  If it was actually not produced by the executable you have
opened with gdb, you will see a warning similar to this:

  
    warning: core file may not match specified executable file.
         Core was generated by `<executable_name>'.
  





GDB Example


This simple example has a segmentation fault - suppose the file name is abc.c:

  

        #include 

    int main( int argc, char ** argv )
    {
        char * abc = NULL;

        strcpy( abc, "DEF" );
        printf( "abc is %s\n", abc );
    }
    
  



First, compile the code with the debug information, then run the executable
in the debugger.  The program dies with a segmentation fault; this will
demonstrate how you might be able to track down the problem with gdb.



      bwall@esus:~/www/cs440/labs$ gcc -o abc -g abc.c

    bwall@esus:~/www/cs440/labs$ gdb abc
    GNU gdb 6.3-debian
    Copyright 2004 Free Software Foundation, Inc.
    GDB is free software, covered by the GNU General Public License, and you are
    welcome to change it and/or distribute copies of it under certain conditions.
    Type "show copying" to see the conditions.
    There is absolutely no warranty for GDB.  Type "show warranty" for details.
    This GDB was configured as "i386-linux"...Using host libthread_db library "/lib>
    
    (gdb) r
    Starting program: /students/bwall/www/cs440/labs/abc
    
    Program received signal SIGSEGV, Segmentation fault.
    0x400945d6 in strcpy () from /lib/libc.so.6

    (gdb) where
    #0  0x400945d6 in strcpy () from /lib/libc.so.6
    #1  0x080483ee in main (argc=1, argv=0xbffff074) at abc.c:7

    (gdb) up
    #1  0x080483ee in main (argc=1, argv=0xbffff074) at abc.c:7
    7           strcpy( abc, "DEF" );

    (gdb) p abc
    $1 = 0x0

    (gdb) kill
    Kill the program being debugged? (y or n) y

    (gdb) start main
    Breakpoint 1 at 0x80483d4: file abc.c, line 5.
    Starting program: /students/bwall/www/cs440/labs/abc main
    main (argc=2, argv=0xbffffa84) at abc.c:5
    5           char * abc = NULL;

    (gdb) n
    7           strcpy( abc, "DEF" );

    (gdb) kill
    Kill the program being debugged? (y or n) y

    (gdb) quit
    bwall@esus:~/www/cs440/labs$ exit
    
    Script done on Mon Oct 10 22:28:10 2005
  



When the program is run, it generates the segmentation fault, and the gdb
where command (you can also use bt or
backtracke) shows the call stack.  This shows that the program
crashed in the strcpy() library function.  Doing up moves
up one stack frame, where you can examine the values of program variables.
The p command (short for print) displays the contents of
variables.  Obviously the pointer abc has a value of NULL (0), which
caused the error in strcpy().  The program is killed and restarted
using the start command to stop upon entry into main().
The n (short for next) command is used to stop over lines one
at a time.