| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
When you 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. If you are doing native debugging, you may redirect your program's input and output, debug an already running process, or kill a child process.
4.1 Compiling for Debugging Compiling for debugging 4.2 Starting your Program Starting your program 4.3 Your Program's Arguments Your program's arguments 4.4 Your Program's Environment Your program's environment
4.5 Your Program's Working Directory Your program's working directory 4.6 Your Program's Input and Output Your program's input and output 4.7 Debugging an Already-running Process Debugging an already-running process 4.8 Killing the Child Process Killing the child process
4.9 Debugging Programs with Multiple Threads Debugging programs with multiple threads 4.10 Debugging Programs with Multiple Processes Debugging programs with multiple processes 4.11 Setting a Bookmark to Return to Later Setting a bookmark to return to later
| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
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.
Programs that are to be shipped to your customers are compiled with optimizations, using the `-O' compiler option. However, many compilers are unable to handle the `-g' and `-O' options together. Using those compilers, you cannot generate optimized executables containing debugging information.
GCC, the GNU C/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 is 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. Do not be too surprised when the execution path does not 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 do not work as well with `-g -O' as with just `-g', particularly on machines with instruction scheduling. If in doubt, recompile with `-g' alone, and if this fixes the problem, please report it to us as a bug (including a test case!). See section 8.2 Program Variables, for more information about debugging optimized code.
Older versions of the GNU C compiler permitted a variant option `-gg' for debugging information. GDB no longer supports this format; if your GNU C compiler has this option, do not use it.
GDB knows about preprocessor macros and can show you their expansion (see section 9. C Preprocessor Macros). Most compilers do not include information about preprocessor macros in the debugging information if you specify the `-g' flag alone, because this information is rather large. Version 3.1 and later of GCC, the GNU C compiler, provides macro information if you specify the options `-gdwarf-2' and `-g3'; the former option requests debugging information in the Dwarf 2 format, and the latter requests "extra information". In the future, we hope to find more compact ways to represent macro information, so that it can be included with `-g' alone.
| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
run
r
run command to start your program under GDB.
You must first specify the program name (except on VxWorks) with an
argument to GDB (see section Getting In and Out of GDB), or by using the file or exec-file command
(see section Commands to Specify Files).
If you are running your program in an execution environment that
supports processes, run creates an inferior process and makes
that process run your program. (In environments without processes,
run jumps to the start of 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 only affect your program the next time you start it.) This information may be divided into four categories:
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 section Your Program's Arguments.
set environment and unset
environment to change parts of the environment that affect
your program. See section Your Program's Environment.
cd command in GDB.
See section Your Program's Working Directory.
run command line, or you can use the tty command to
set a different device for your program.
See section Your Program's Input and Output.
Warning: While input and output redirection work, you cannot use pipes to pass the output of the program you are debugging to another program; if you attempt this, GDB is likely to wind up debugging the wrong program.
When you issue the run command, your program begins to execute
immediately. See section Stopping and Continuing, for discussion
of how to arrange for your program to stop. Once your program has
stopped, you may call functions in your program, using the print
or call commands. See section Examining Data.
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.
start
The name of the main procedure can vary from language to language.
With C or C++, the main procedure name is always main, but
other languages such as Ada do not require a specific name for their
main procedure. The debugger provides a convenient way to start the
execution of the program and to stop at the beginning of the main
procedure, depending on the language used.
The `start' command does the equivalent of setting a temporary breakpoint at the beginning of the main procedure and then invoking the `run' command.
Some programs contain an elaboration phase where some startup code is
executed before the main procedure is called. This depends on the
languages used to write your program. In C++, for instance,
constructors for static and global objects are executed before
main is called. It is therefore possible that the debugger stops
before reaching the main procedure. However, the temporary breakpoint
will remain to halt execution.
Specify the arguments to give to your program as arguments to the `start' command. These arguments will be given verbatim to the underlying `run' command. Note that the same arguments will be reused if no argument is provided during subsequent calls to `start' or `run'.
It is sometimes necessary to debug the program during elaboration. In
these cases, using the start command would stop the execution of
your program too late, as the program would have already completed the
elaboration phase. Under these circumstances, insert breakpoints in your
elaboration code before running your program.
| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
The arguments to your program can be specified by the arguments of the
run command.
They are passed to a shell, which expands wildcard characters and
performs redirection of I/O, and thence to your program. Your
SHELL environment variable (if it exists) specifies what shell
GDB uses. If you do not define SHELL, GDB uses
the default shell (`/bin/sh' on Unix).
On non-Unix systems, the program is usually invoked directly by GDB, which emulates I/O redirection via the appropriate system calls, and the wildcard characters are expanded by the startup code of the program, not by the shell.
run with no arguments uses the same arguments used by the previous
run, or those set by the set args command.
set args
set args has no arguments, run executes your program
with no arguments. Once you have run your program with arguments,
using set args before the next run is the only way to run
it again without arguments.
show args
| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
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 are 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.
path directory
PATH environment variable
(the search path for executables) that will be passed to your program.
The value of PATH used by GDB does not change.
You may specify several directory names, separated by whitespace or by a
system-dependent separator character (`:' on Unix, `;' on
MS-DOS and MS-Windows). If directory is already in the path, it
is moved to the front, so it is searched sooner.
You can use the string `$cwd' to refer to whatever is the current
working directory at the time GDB searches the path. If you
use `.' instead, it refers to the directory where you executed the
path command. GDB replaces `.' in the
directory argument (with the current path) before adding
directory to the search path.
show paths
PATH
environment variable).
show environment [varname]
environment as env.
set environment varname [=value]
For example, this command:
set env USER = foo
tells the debugged program, when subsequently run, that its user is named `foo'. (The spaces around `=' are used for clarity here; they are not actually required.)
unset environment varname
unset environment removes the variable from the environment,
rather than assigning it an empty value.
Warning: On Unix systems, GDB runs your program using
the shell indicated
by your SHELL environment variable if it exists (or
/bin/sh if not). If your SHELL variable names a shell
that runs an initialization file--such as `.cshrc' for C-shell, or
`.bashrc' for BASH--any variables you set in that file affect
your program. You may wish to move setting of environment variables to
files that are only run when you sign on, such as `.login' or
`.profile'.
| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
Each time you start your program with run, it inherits its
working directory from the current working directory of GDB.
The GDB working directory is initially whatever it inherited
from its parent process (typically the shell), but you can specify a new
working directory in GDB with the cd command.
The GDB working directory also serves as a default for the commands that specify files for GDB to operate on. See section Commands to Specify Files.
cd directory
pwd
It is generally impossible to find the current working directory of
the process being debugged (since a program can change its directory
during its run). If you work on a system where GDB is
configured with the `/proc' support, you can use the info
proc command (see section 18.1.3 SVR4 Process Information) to find out the
current working directory of the debuggee.
| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
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.
info terminal
You can redirect your program's input and/or output using shell
redirection with the run command. For example,
run > outfile
starts your program, diverting its output to the file `outfile'.
Another way to specify where your program should do input and output is
with the tty command. This command accepts a file name as
argument, and causes this file to be the default for future run
commands. It also resets the controlling terminal for the child
process, for future run commands. For example,
tty /devlab/ttyb
directs that processes started with subsequent run commands
default to do input and output on the terminal `/devlab/ttyb' and have
that as their controlling terminal.
An explicit redirection in run overrides the tty command's
effect on the input/output device, but not its effect on the controlling
terminal.
When you use the tty command or redirect input in the run
command, only the input for your program is affected. The input
for GDB still comes from your terminal. tty is an alias
for set inferior-tty.
You can use the show inferior-tty command to tell GDB to
display the name of the terminal that will be used for future runs of your
program.
set inferior-tty /devlab/ttyb
Set the tty for the program being debugged to /devlab/ttyb.
show inferior-tty
Show the current tty for the program being debugged.
| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
attach process-id
info files shows your active
targets.) The command takes as argument a process ID. The usual way to
find out the process-id of a Unix process is with the ps utility,
or with the `jobs -l' shell command.
attach does not repeat if you press RET a second time after
executing the command.
To use attach, your program must be running in an environment
which supports processes; for example, attach does not work for
programs on bare-board targets that lack an operating system. You must
also have permission to send the process a signal.
When you use attach, the debugger finds the program running in
the process first by looking in the current working directory, then (if
the program is not found) by using the source file search path
(see section Specifying Source Directories). You can also use
the file command to load the program. See section Commands to Specify Files.
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 would rather the
process continue running, you may use the continue command after
attaching GDB to the process.
detach
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
are ready to attach another process or start one with run.
detach does not repeat if you press RET again after
executing the command.
If you exit GDB while you have an attached process, you detach
that process. If you use the run command, 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 (see section Optional Warnings and Messages).
| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
kill
This command is useful if you wish to debug a core dump instead of a running process. GDB ignores any core dump file while your program is running.
On some operating systems, a program cannot be executed outside GDB
while you have breakpoints set on it inside GDB. You can use the
kill command in this situation to permit running your program
outside the debugger.
The kill command is also useful if you wish to recompile and
relink your program, since on many systems it is impossible to modify an
executable file while it is running in a process. In this case, 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).
| [ <] | [ >] | [ <<] | [ Up] | [ >>] | [Top] | [Contents] | [Index] | [ ?] |
In some operating systems, such as HP-UX and Solaris, a single program may have more than one thread of execution. The precise semantics of threads differ from one operating system to another, but in general the threads of a single program are akin to multiple processes--except that they share one address space (that is, they can all examine and modify the same variables). On the other hand, each thread has its own registers and execution stack, and perhaps private memory.
GDB provides these facilities for debugging multi-thread programs: