5.3. GDB

⁠5.3. GDB

Fundamentally, like most debuggers, GDB manages the execution of compiled code in a very closely controlled environment. This environment makes possible the following fundamental mechanisms necessary to the operation of GDB:

Inspect and modify memory within the code being debugged (for example, reading and setting variables).
Control the execution state of the code being debugged, principally whether it's running or stopped.
Detect the execution of particular sections of code (for example, stop running code when it reaches a specified area of interest to the programmer).
Detect access to particular areas of memory (for example, stop running code when it accesses a specified variable).
Execute portions of code (from an otherwise stopped program) in a controlled manner.
Detect various programmatic asynchronous events such as signals.

The operation of these mechanisms rely mostly on information produced by a compiler. For example, to view the value of a variable, GDB has to know:

The location of the variable in memory
The nature of the variable

This means that displaying a double-precision floating point value requires a very different process from displaying a string of characters. For something complex like a structure, GDB has to know not only the characteristics of each individual elements in the structure, but the morphology of the structure as well.

GDB requires the following items in order to fully function:

Debug Information: Much of GDB's operations rely on a program's debug information. While this information generally comes from compilers, much of it is necessary only while debugging a program, that is, it is not used during the program's normal execution. For this reason, compilers do not always make that information available by default — GCC, for instance, must be explicitly instructed to provide this debugging information with the -g flag.
To make full use of GDB's capabilities, it is highly advisable to make the debug information available first to GDB. GDB can only be of very limited use when run against code with no available debug information.
Source Code: One of the most useful features of GDB (or any other debugger) is the ability to associate events and circumstances in program execution with their corresponding location in source code. This location normally refers to a specific line or series of lines in a source file. This, of course, would require that a program's source code be available to GDB at debug time.

⁠5.3.1. Simple GDB

GDB literally contains dozens of commands. This section describes the most fundamental ones.

br (breakpoint): The breakpoint command instructs GDB to halt execution upon reaching a specified point in the execution. That point can be specified a number of ways, but the most common are just as the line number in the source file, or the name of a function. Any number of breakpoints can be in effect simultaneously. This is frequently the first command issued after starting GDB.
r (run): The run command starts the execution of the program. If run is executed with any arguments, those arguments are passed on to the executable as if the program has been started normally. Users normally issue this command after setting breakpoints.

Before an executable is started, or once the executable stops at, for example, a breakpoint, the state of many aspects of the program can be inspected. The following commands are a few of the more common ways things can be examined.

p (print): The print command displays the value of the argument given, and that argument can be almost anything relevant to the program. Usually, the argument is the name of a variable of any complexity, from a simple single value to a structure. An argument can also be an expression valid in the current language, including the use of program variables and library functions, or functions defined in the program being tested.
bt (backtrace): The backtrace displays the chain of function calls used up until the execution was terminated. This is useful for investigating serious bugs (such as segmentation faults) with elusive causes.
l (list): When execution is stopped, the list command shows the line in the source code corresponding to where the program stopped.

The execution of a stopped program can be resumed in a number of ways. The following are the most common.

c (continue): The continue command restarts the execution of the program, which will continue to execute until it encounters a breakpoint, runs into a specified or emergent condition (for example, an error), or terminates.
n (next): Like continue, the next command also restarts execution; however, in addition to the stopping conditions implicit in the continue command, next will also halt execution at the next sequential line of code in the current source file.
s (step): Like next, the step command also halts execution at each sequential line of code in the current source file. However, if execution is currently stopped at a source line containing a function call, GDB stops execution after entering the function call (rather than executing it).
fini (finish): Like the aforementioned commands, the finish command resumes executions, but halts when execution returns from a function.

Finally, two essential commands:

q (quit): This terminates the execution.
h (help): The help command provides access to its extensive internal documentation. The command takes arguments: help breakpoint (or h br), for example, shows a detailed description of the breakpoint command. See the help output of each command for more detailed information.

⁠5.3.2. Running GDB

This section will describe a basic execution of GDB, using the following simple program:

⁠

hello.c

#include <stdio.h>

char hello[] = { "Hello, World!" };

int
main()
{
  fprintf (stdout, "%s\n", hello);
  return (0);
}

The following procedure illustrates the debugging process in its most basic form.

⁠

Procedure 5.1. Debugging a 'Hello World' Program

Compile hello.c into an executable with the debug flag set, as in:
gcc -g -o hello hello.c
Ensure that the resulting binary hello is in the same directory as hello.c.
Run gdb on the hello binary, that is, gdb hello.
After several introductory comments, gdb will display the default GDB prompt:
```
(gdb)
```
The variable hello is global, so it can be seen even before the main procedure starts:
```
gdb) p hello
$1 = "Hello, World!"
(gdb) p hello[0]
$2 = 72 'H'
(gdb) p *hello
$3 = 72 'H'
(gdb)
```
Note that the print targets hello[0] and *hello require the evaluation of an expression, as does, for example, *(hello + 1):
```
(gdb) p *(hello + 1)
$4 = 101 'e'
```

Next, list the source:

(gdb) l
1       #include <stdio.h>
2
3       char hello[] = { "Hello, World!" };
4
5       int
6       main()
7       {
8         fprintf (stdout, "%s\n", hello);
9         return (0);
10      }

The list reveals that the fprintf call is on line 8. Apply a breakpoint on that line and resume the code:

(gdb) br 8
Breakpoint 1 at 0x80483ed: file hello.c, line 8.
(gdb) r
Starting program: /home/moller/tinkering/gdb-manual/hello

Breakpoint 1, main () at hello.c:8
8         fprintf (stdout, "%s\n", hello);

Finally, use the next command to step past the fprintf call, executing it:
```
(gdb) n
Hello, World!
9         return (0);
```

The following sections describe more complex applications of GDB.

⁠5.3.3. Conditional Breakpoints

In many real-world cases, a program may perform its task well during the first few thousand times; it may then start crashing or encountering errors during its eight thousandth iteration of the task. Debugging programs like this can be difficult, as it is hard to imagine a programmer with the patience to issue a continue command thousands of times just to get to the iteration that crashed.

Situations like this are common in real life, which is why GDB allows programmers to attach conditions to a breakpoint. For example, consider the following program:

⁠

simple.c

#include <stdio.h>

main()
{
  int i;

  for (i = 0;; i++) {
fprintf (stdout, "i = %d\n", i);
  }
}

To set a conditional breakpoint at the GDB prompt:

(gdb) br 8 if i == 8936
Breakpoint 1 at 0x80483f5: file iterations.c, line 8.
(gdb) r

With this condition, the program execution will eventually stop with the following output:

i = 8931
i = 8932
i = 8933
i = 8934
i = 8935

Breakpoint 1, main () at iterations.c:8
8           fprintf (stdout, "i = %d\n", i);

Inspect the breakpoint information (using info br) to review the breakpoint status:

(gdb) info br
Num     Type           Disp Enb Address    What
1       breakpoint     keep y   0x080483f5 in main at iterations.c:8
        stop only if i == 8936
        breakpoint already hit 1 time

⁠5.3.4. Forked Execution

Among the more challenging bugs confronting programmers is where one program (the parent) makes an independent copy of itself (a fork). That fork then creates a child process which, in turn, fails. Debugging the parent process may or may not be useful. Often the only way to get to the bug may be by debugging the child process, but this is not always possible.

The set follow-fork-mode feature is used to overcome this barrier allowing programmers to follow a a child process instead of the parent process.

set follow-fork-mode parent: The original process is debugged after a fork. The child process runs unimpeded. This is the default.
set follow-fork-mode child: The new process is debugged after a fork. The parent process runs unimpeded.
show follow-fork-mode: Display the current debugger response to a fork call.

Use the set detach-on-fork command to debug both the parent and the child processes after a fork, or retain debugger control over them both.

set detach-on-fork on: The child process (or parent process, depending on the value of follow-fork-mode) will be detached and allowed to run independently. This is the default.
set detach-on-fork off: Both processes will be held under the control of GDB. One process (child or parent, depending on the value of follow-fork-mode) is debugged as usual, while the other is suspended.
show detach-on-fork: Show whether detach-on-fork mode is on or off.

Consider the following program:

fork.c

#include <unistd.h>

int main()
{
  pid_t  pid;
  const char *name;

  pid = fork();
  if (pid == 0)
    {
      name = "I am the child";
    }
  else
    {
      name = "I am the parent";
    }
  return 0;
}

This program, compiled with the command gcc -g fork.c -o fork -lpthread and examined under GDB will show:

gdb ./fork
[...]
(gdb) break main
Breakpoint 1 at 0x4005dc: file fork.c, line 8.
(gdb) run
[...]
Breakpoint 1, main () at fork.c:8
8   pid = fork();
(gdb) next
Detaching after fork from child process 3840.
9   if (pid == 0)
(gdb) next
15       name = "I am the parent";
(gdb) next
17   return 0;
(gdb) print name
$1 = 0x400717 "I am the parent"

GDB followed the parent process and allowed the child process (process 3840) to continue execution.

The following is the same test using set follow-fork-mode child.

(gdb) set follow-fork-mode child
(gdb) break main
Breakpoint 1 at 0x4005dc: file fork.c, line 8.
(gdb) run
[...]
Breakpoint 1, main () at fork.c:8
8	  pid = fork();
(gdb) next
[New process 3875]
[Thread debugging using libthread_db enabled]
[Switching to Thread 0x7ffff7fd5720 (LWP 3875)]
9	  if (pid == 0)
(gdb) next
11	      name = "I am the child";
(gdb) next
17	  return 0;
(gdb) print name
$2 = 0x400708 "I am the child"
(gdb)

GDB switched to the child process here.

This can be permanent by adding the setting to the appropriate .gdbinit.

For example, if set follow-fork-mode ask is added to ~/.gdbinit, then ask mode becomes the default mode.

⁠5.3.5. Debugging Individual Threads

GDB has the ability to debug individual threads, and to manipulate and examine them independently. This functionality is not enabled by default. To do so use set non-stop on and set target-async on. These can be added to .gdbinit. Once that functionality is turned on, GDB is ready to conduct thread debugging.

For example, the following program creates two threads. These two threads, along with the original thread executing main makes a total of three threads.

three-threads.c

#include <stdio.h>
#include <pthread.h>
#include <unistd.h>

pthread_t thread;

void* thread3 (void* d)
{
  int count3 = 0;

  while(count3 < 1000){
    sleep(10);
    printf("Thread 3: %d\n", count3++);
  }
  return NULL;
}

void* thread2 (void* d)
{
  int count2 = 0;

  while(count2 < 1000){
    printf("Thread 2: %d\n", count2++);
  }
  return NULL;
}

int main (){

  pthread_create (&thread, NULL, thread2, NULL);
  pthread_create (&thread, NULL, thread3, NULL);
  
  //Thread 1
  int count1 = 0;

  while(count1 < 1000){
    printf("Thread 1: %d\n", count1++);
  }

  pthread_join(thread,NULL);
  return 0;
}

Compile this program in order to examine it under GDB.

gcc -g three-threads.c -o three-threads  -lpthread
gdb ./three-threads

First set breakpoints on all thread functions; thread1, thread2, and main.

(gdb) break thread3
Breakpoint 1 at 0x4006c0: file three-threads.c, line 9.
(gdb) break thread2
Breakpoint 2 at 0x40070c: file three-threads.c, line 20.
(gdb) break main
Breakpoint 3 at 0x40074a: file three-threads.c, line 30.

Then run the program.

(gdb) run
[...]
Breakpoint 3, main () at three-threads.c:30
30	  pthread_create (&thread, NULL, thread2, NULL);
[...]
(gdb) info threads
* 1 Thread 0x7ffff7fd5720 (LWP 4620)  main () at three-threads.c:30
(gdb)

Note that the command info threads provides a summary of the program's threads and some details about their current state. In this case there is only one thread that has been created so far.

Continue execution some more.

(gdb) next
[New Thread 0x7ffff7fd3710 (LWP 4687)]
31	  pthread_create (&thread, NULL, thread3, NULL);
(gdb) 
Breakpoint 2, thread2 (d=0x0) at three-threads.c:20
20	  int count2 = 0;
next
[New Thread 0x7ffff75d2710 (LWP 4688)]
34	  int count1 = 0;
(gdb) 
Breakpoint 1, thread3 (d=0x0) at three-threads.c:9
9	  int count3 = 0;
info threads
  3 Thread 0x7ffff75d2710 (LWP 4688)  thread3 (d=0x0) at three-threads.c:9
  2 Thread 0x7ffff7fd3710 (LWP 4687)  thread2 (d=0x0) at three-threads.c:20
* 1 Thread 0x7ffff7fd5720 (LWP 4620)  main () at three-threads.c:34

Here, two more threads are created. The star indicates the thread currently under focus. Also, the newly created threads have hit the breakpoint set for them in their initialization functions. Namely, thread2() and thread3().

To begin real thread debugging, use the thread <thread number> command to switch the focus to another thread.

(gdb) thread 2
[Switching to thread 2 (Thread 0x7ffff7fd3710 (LWP 4687))]#0  thread2 (d=0x0)
    at three-threads.c:20
20	  int count2 = 0;
(gdb) list
15	  return NULL;
16	}
17	
18	void* thread2 (void* d)
19	{
20	  int count2 = 0;
21	
22	  while(count2 < 1000){
23	    printf("Thread 2: %d\n", count2++);
24	  }

Thread 2 stopped at line 20 in its function thread2().

(gdb) next
22	  while(count2 < 1000){
(gdb) print count2
$1 = 0
(gdb) next
23	    printf("Thread 2: %d\n", count2++);
(gdb) next
Thread 2: 0
22	  while(count2 < 1000){
(gdb) next
23	    printf("Thread 2: %d\n", count2++);
(gdb) print count2
$2 = 1
(gdb) info threads
  3 Thread 0x7ffff75d2710 (LWP 4688)  thread3 (d=0x0) at three-threads.c:9
* 2 Thread 0x7ffff7fd3710 (LWP 4687)  thread2 (d=0x0) at three-threads.c:23
  1 Thread 0x7ffff7fd5720 (LWP 4620)  main () at three-threads.c:34
(gdb)

Above, a few lines of thread2 printed the counter count2 and left thread 2 at line 23 as is seen by the output of 'info threads'.

Now thread3.

(gdb) thread 3
[Switching to thread 3 (Thread 0x7ffff75d2710 (LWP 4688))]#0  thread3 (d=0x0)
    at three-threads.c:9
9	  int count3 = 0;
(gdb) list
4	
5	pthread_t thread;
6	
7	void* thread3 (void* d)
8	{
9	  int count3 = 0;
10	
11	  while(count3 < 1000){
12	    sleep(10);
13	    printf("Thread 3: %d\n", count3++);
(gdb)

Thread three is a little different in that it has a sleep statement and executes slowly. Think of it as a representation of an uninteresting IO thread. Because this thread is uninteresting, continue its execution uninterrupted, using the continue.

(gdb) continue &
(gdb) Thread 3: 0
Thread 3: 1
Thread 3: 2
Thread 3: 3

Take note of the & at the end of the continue. This allows the GDB prompt to return so other commands can be executed. Using the interrupt, execution can be stopped should thread 3 become interesting again.

(gdb) interrupt
[Thread 0x7ffff75d2710 (LWP 4688)] #3 stopped.
0x000000343f4a6a6d in nanosleep () at ../sysdeps/unix/syscall-template.S:82
82	T_PSEUDO (SYSCALL_SYMBOL, SYSCALL_NAME, SYSCALL_NARGS)

It is also possible to go back to the original main thread and examine it some more.

(gdb) thread 1
[Switching to thread 1 (Thread 0x7ffff7fd5720 (LWP 4620))]#0  main ()
    at three-threads.c:34
34	  int count1 = 0;
(gdb) next
36	  while(count1 < 1000){
(gdb) next
37	    printf("Thread 1: %d\n", count1++);
(gdb) next
Thread 1: 0
36	  while(count1 < 1000){
(gdb) next
37	    printf("Thread 1: %d\n", count1++);
(gdb) next
Thread 1: 1
36	  while(count1 < 1000){
(gdb) next
37	    printf("Thread 1: %d\n", count1++);
(gdb) next
Thread 1: 2
36	  while(count1 < 1000){
(gdb) print count1 
$3 = 3
(gdb) info threads 
  3 Thread 0x7ffff75d2710 (LWP 4688)  0x000000343f4a6a6d in nanosleep ()
    at ../sysdeps/unix/syscall-template.S:82
  2 Thread 0x7ffff7fd3710 (LWP 4687)  thread2 (d=0x0) at three-threads.c:23
* 1 Thread 0x7ffff7fd5720 (LWP 4620)  main () at three-threads.c:36
(gdb)

As can be seen from the output of info threads, the other threads are where they were left, unaffected by the debugging of thread 1.

⁠5.3.6. Alternative User Interfaces for GDB

GDB uses the command line as its default interface. However, it also has an API called machine interface (MI). MI allows IDE developers to create other user interfaces to GDB.

Some examples of these interfaces are:

Eclipse (CDT): A graphical debugger interface integrated with the Eclipse development environment. More information can be found at the Eclipse website.
Nemiver: A graphical debugger interface which is well suited to the GNOME Desktop Environment. More information can be found at the Nemiver website
Emacs: A GDB interface which is integrated with the emacs. More information can be found at the Emacs website

⁠5.3.7. GDB Documentation

For more detailed information about GDB, see the GDB manual:

http://sources.redhat.com/gdb/current/onlinedocs/gdb.html

Also, the commands info gdb and man gdb will provide more concise information that is up to date with the installed version of gdb.