Running programs under GDB

To run a program under GDB, you must first generate debugging information when you compile it. You may start GDB with its arguments, if any, in an environment of your choice. You may redirect your program's input and output, debug an already running process, or kill the process being debugged.

Compiling for debugging

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.

GCC, the GNU C compiler, supports -g with or without -O, making it possible to debug optimized code. We recommend that you always use -g whenever you compile a program. You may think your program is correct, but there's no sense in pushing your luck.

When you debug a program compiled with -g -O, remember that the optimizer is rearranging your code; the debugger shows you what is really there. Don't be too surprised when the execution path doesn't exactly match your source file! An extreme example: if you define a variable, but never use it, GDB never sees that variable—because the compiler optimizes it out of existence.

Some things don't work as well with -g -O as with just -g, particularly on machines with instruction scheduling. If in doubt, recompile with -g alone.

Setting the target

If you're debugging locally, you don't need to specify the target (or you can specify target procfs).

If you're debugging remotely, you need to specify the target to use:

target qnx com_port_specifier | host:port | pty

The pty option spawns a pdebug server on the local machine and connects via a pty.

The devc-pty manager must be running on the machine that's running pdebug, and a ptyp/ttyp pair must be available.

Starting your program

The execution of a program is affected by certain information it receives from its superior. GDB provides ways to specify this information, which you must do before starting your program. (You can change it after starting your program, but such changes affect your program the next time you start it.) This information may be divided into the following categories:

set nto-cwd path
Specify the remote process's working directory. You should do this before starting your program.
run or r
Use the run command to start your program under GDB. You must first specify the program name with an argument to GDB (see the description of the gdb utility).

The run creates an inferior process and makes that process run your program.

Specify the arguments to give your program as the arguments of the run command. If a shell is available on your target, the shell is used to pass the arguments, so that you may use normal conventions (such as wildcard expansion or variable substitution) in describing the arguments. In Unix systems, you can control which shell is used with the SHELL environment variable. See Your program's arguments.
Your program normally inherits its environment from GDB, but you can use the GDB commands set environment and unset environment to change parts of the environment that affect your program. See Your program's environment.

While input and output redirection work, you can't use pipes to pass the output of the program you're debugging to another program; if you attempt this, GDB is likely to wind up debugging the wrong program.

If the modification time of your symbol file has changed since the last time GDB read its symbols, GDB discards its symbol table and reads it again. When it does this, GDB tries to retain your current breakpoints.

Here's an example of starting a program for local debugging:

(gdb) file /tmp/helloworld
Reading symbols from /tmp/helloworld...done.
(gdb) b main
Breakpoint 1 at 0x804860c: file ./main.c, line 5.
(gdb) r
Starting program:
Remote: /tmp/helloworld

Breakpoint 1, main () at ./main.c:5
5       {

Here's an example of starting the program for remote debugging:

(gdb) target qnx mytst:8000
Remote debugging using mytst:8000
Remote target is little-endian
(gdb) file /tmp/helloworld
Reading symbols from /tmp/helloworld...done.
(gdb) upload /tmp/helloworld /tmp/helloworld
(gdb) b main
Breakpoint 1 at 0x804860c: file ./main.c, line 5.
(gdb) r
Starting program:
Remote: /tmp/helloworld

Breakpoint 1, main () at ./main.c:5
5       {

If your communication line is slow, you might need to set the timeout for remote reads:

set nto-timeout time

where time is the timeout, in seconds. The default is 10 seconds.

Your program's arguments

The arguments to your program can be specified by the arguments of the run command.

A run command with no arguments uses the same arguments used by the previous run, or those set by the set args command.

set args
Specify the arguments to be used the next time your program is run. If set args has no arguments, run executes your program with no arguments. Once you've run your program with arguments, using set args before the next run is the only way to run it again without arguments.
show args
Show the arguments to give your program when it's started.

Your program's environment

The environment consists of a set of environment variables and their values. Environment variables conventionally record such things as your user name, your home directory, your terminal type, and your search path for programs to run. Usually you set up environment variables with the shell and they're inherited by all the other programs you run. When debugging, it can be useful to try running your program with a modified environment without having to start GDB over again.

set nto-inherit-env value
If value is 0, the process inherits its environment from GDB. If value is 1 (the default), the process inherits its environment from pdebug.
path directory
Add directory to the front of the PATH environment variable (the search path for executables), for both GDB and your program. You may specify several directory names, separated by a colon (:) or whitespace. If directory is already in the path, it's moved to the front, so it's searched sooner.

You can use the string $cwd to refer to the current working directory at the time GDB searches the path. A period (.) refers to the directory where you executed the path command. GDB replaces the period in the directory argument by the current path before adding directory to the search path.

show paths
Display the list of search paths for executables (the PATH environment variable).
show environment [varname]
Print the value of environment variable varname to be given to your program when it starts. If you don't supply varname, print the names and values of all environment variables to be given to your program. You can abbreviate environment as env.
set environment varname [=] value
Set environment variable varname to value. The value changes for your program only, not for GDB itself. The value may be any string; the values of environment variables are just strings, and any interpretation is supplied by your program itself. The value parameter is optional; if it's eliminated, the variable is set to a null value.

For example, this command:

set env USER=foo

tells a Unix program, when subsequently run, that its user is named foo.
unset environment varname
Remove variable varname from the environment to be passed to your program. This is different from set env varname =, in that unset environment removes the variable from the environment, rather than assign it an empty value.

Your program's input and output

By default, the program you run under GDB does input and output to the same terminal that GDB uses. GDB switches the terminal to its own terminal modes to interact with you, but it records the terminal modes your program was using and switches back to them when you continue running your program.

You can redirect your program's input and/or output using shell redirection with the run command. For example:

run > outfile

This starts your program, diverting its output to the file outfile.

Debugging an already-running process

To use attach, you must have permission to send the process a signal.

attach process-id
This command attaches to a running process—one that was started outside GDB. (The info files command shows your active targets.) The command takes as its argument a process ID. To find out a process ID, use the pidin utility (see the Utilities Reference), or use GDB's info pidlist command.

The attach command doesn't repeat if you press Enter a second time after executing the command.

When using attach, you should first use the file command to specify the program running in the process and load its symbol table.

The first thing GDB does after arranging to debug the specified process is to stop it. You can examine and modify an attached process with all the GDB commands that are ordinarily available when you start processes with run. You can insert breakpoints; you can step and continue; you can modify storage. If you want the process to continue running, use the continue command after attaching GDB to the process.

When you've finished debugging the attached process, you can use the detach command to release it from GDB control. Detaching the process continues its execution. After the detach command, that process and GDB become completely independent once more, and you're ready to attach another process or start one with run. The detach command doesn't repeat if you press Enter again after executing the command.

If you exit GDB or use the run command while you have an attached process, you kill that process. By default, GDB asks for confirmation if you try to do either of these things; you can control whether or not you need to confirm by using the set confirm command.

Killing the process being debugged

This command is useful if you want to debug a core dump instead of a running process. GDB ignores any core dump file while your program is running.

Kill the process being debugged.

The kill command is also useful if you want to recompile and relink your program. With BlackBerry 10 OS, it's possible to modify an executable file while it's running in a process. If you want to run the new version, kill the current process; when you next type run, GDB notices that the file has changed, and reads the symbol table again (while trying to preserve your current breakpoint settings).

Debugging programs with multiple threads

In BlackBerry 10 OS, a single program may have more than one thread of execution. Each thread has its own registers and execution stack, and perhaps private memory.

GDB provides these facilities for debugging multithreaded programs:

  • thread threadno, a command to switch between threads
  • info threads, a command to inquire about existing threads
  • thread apply [threadno] [all] args, a command to apply a command to a list of threads
  • thread-specific breakpoints

The GDB thread debugging facility lets you observe all threads while your program runs—but whenever GDB takes control, one thread in particular is always the focus of debugging. This thread is called the current thread. Debugging commands show program information from the perspective of the current thread.

GDB associates its own thread number—always a single integer—with each thread in your program.

info threads
Display a summary of all threads currently in your program. GDB displays for each thread (in this order):
  1. Thread number assigned by GDB
  2. Target system's thread identifier (systag)
  3. Current stack frame summary for that thread.

An asterisk * to the left of the GDB thread number indicates the current thread. For example:

(gdb) info threads
  3 process 35 thread 27  0x34e5 in sigpause ()
  2 process 35 thread 23  0x34e5 in sigpause ()
* 1 process 35 thread 13  main (argc=1, argv=0x7ffffff8)
    at threadtest.c:68
thread threadno
Make thread number threadno the current thread. The command argument threadno is the internal GDB thread number, as shown in the first field of the info threads display. GDB responds by displaying the system identifier of the thread you selected and its current stack frame summary:

(gdb) thread 2
[Switching to process 35 thread 23]
0x34e5 in sigpause ()
thread apply [threadno] [all] args
The thread apply command lets you apply a command to one or more threads. Specify the numbers of the threads that you want affected with the command argument threadno. To apply a command to all threads, use thread apply all args.

Whenever GDB stops your program because of a breakpoint or a signal, it automatically selects the thread where that breakpoint or signal happened. GDB alerts you to the context switch with a message of the form [Switching to systag] to identify the thread.

See Stopping and starting multithreaded programs for more information about how GDB behaves when you stop and start programs with multiple threads.

See Setting watchpoints for information about watchpoints in programs with multiple threads.

Debugging programs with multiple processes

GDB has no special support for debugging programs that create additional processes using the fork() function. When a program forks, GDB continues to debug the parent process, and the child process runs unimpeded. If you've set a breakpoint in any code that the child then executes, the child gets a SIGTRAP signal, which (unless it catches the signal) causes it to terminate.

However, if you want to debug the child process, there's a workaround that isn't too painful:

  1. Put a call to sleep() in the code that the child process executes after the fork(). It may be useful to sleep only if a certain environment variable is set, or a certain file exists, so that the delay doesn't occur when you don't want to run GDB on the child.
  2. While the child is sleeping, get its process ID by using the pidin utility (see the Utilities Reference) or by using GDB's info pidlist command.
  3. Tell GDB (a new invocation of GDB if you're also debugging the parent process) to attach to the child process (see Debugging an already-running process). From that point on you can debug the child process just like any other process that you've attached to.

Last modified: 2015-05-07

Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus