neingeist/arduinisten
Archived
1
0
Fork 0
Code Releases Activity
This repository has been archived on 2019-12-23. You can view files and clone it, but you cannot make any changes to it's state, such as pushing and creating new issues, pull requests or comments.
arduinisten/arduino-0018-windows/hardware/tools/avr/doc/gdb/onlinedocs/gdb_5.html
orange f39fc49523 arduino-0018-windows
2010-03-30 21:53:44 +02:00

1380 lines
59 KiB
HTML
Raw Blame History

<HTML>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created on March, 27 2008 by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HEAD>
<TITLE>Debugging with GDB: Running</TITLE>
<META NAME="description" CONTENT="Debugging with GDB: Running">
<META NAME="keywords" CONTENT="Debugging with GDB: Running">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC18"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_4.html#SEC17"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC19"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H1> 4. Running Programs Under GDB </H1>
<!--docid::SEC18::-->
<P>
When you run a program under GDB, you must first generate
debugging information when you compile it.
</P><P>
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.
</P><P>
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC19">4.1 Compiling for Debugging</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Compiling for debugging</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC20">4.2 Starting your Program</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Starting your program</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC21">4.3 Your Program's Arguments</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Your program's arguments</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC22">4.4 Your Program's Environment</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Your program's environment</TD></TR>
</TABLE>
<br>
<TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC23">4.5 Your Program's Working Directory</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Your program's working directory</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC24">4.6 Your Program's Input and Output</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Your program's input and output</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC25">4.7 Debugging an Already-running Process</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Debugging an already-running process</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC26">4.8 Killing the Child Process</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Killing the child process</TD></TR>
</TABLE>
<br>
<TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC27">4.9 Debugging Programs with Multiple Threads</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Debugging programs with multiple threads</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC28">4.10 Debugging Programs with Multiple Processes</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Debugging programs with multiple processes</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_5.html#SEC29">4.11 Setting a <EM>Bookmark</EM> to Return to Later</A></TD><TD>&nbsp;&nbsp;</TD><TD ALIGN="left" VALIGN="TOP">Setting a <EM>bookmark</EM> to return to later</TD></TR>
</TABLE></BLOCKQUOTE>
<P>
<A NAME="Compilation"></A>
<HR SIZE="6">
<A NAME="SEC19"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC20"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.1 Compiling for Debugging </H2>
<!--docid::SEC19::-->
<P>
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.
</P><P>
To request debugging information, specify the <SAMP>`-g'</SAMP> option when you run
the compiler.
</P><P>
Programs that are to be shipped to your customers are compiled with
optimizations, using the <SAMP>`-O'</SAMP> compiler option. However, many
compilers are unable to handle the <SAMP>`-g'</SAMP> and <SAMP>`-O'</SAMP> options
together. Using those compilers, you cannot generate optimized
executables containing debugging information.
</P><P>
GCC, the GNU C/C<TT>++</TT> compiler, supports <SAMP>`-g'</SAMP> with or
without <SAMP>`-O'</SAMP>, making it possible to debug optimized code. We
recommend that you <EM>always</EM> use <SAMP>`-g'</SAMP> whenever you compile a
program. You may think your program is correct, but there is no sense
in pushing your luck.
</P><P>
<A NAME="IDX89"></A>
<A NAME="IDX90"></A>
When you debug a program compiled with <SAMP>`-g -O'</SAMP>, 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.
</P><P>
Some things do not work as well with <SAMP>`-g -O'</SAMP> as with just
<SAMP>`-g'</SAMP>, particularly on machines with instruction scheduling. If in
doubt, recompile with <SAMP>`-g'</SAMP> alone, and if this fixes the problem,
please report it to us as a bug (including a test case!).
See section <A HREF="gdb_9.html#SEC61">8.2 Program Variables</A>, for more information about debugging optimized code.
</P><P>
Older versions of the GNU C compiler permitted a variant option
<SAMP>`-gg'</SAMP> for debugging information. GDB no longer supports this
format; if your GNU C compiler has this option, do not use it.
</P><P>
GDB knows about preprocessor macros and can show you their
expansion (see section <A HREF="gdb_10.html#SEC83">9. C Preprocessor Macros</A>). Most compilers do not include information
about preprocessor macros in the debugging information if you specify
the <SAMP>`-g'</SAMP> 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
<SAMP>`-gdwarf-2'</SAMP> and <SAMP>`-g3'</SAMP>; 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
<SAMP>`-g'</SAMP> alone.
</P><P>
<A NAME="Starting"></A>
<HR SIZE="6">
<A NAME="SEC20"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC19"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC21"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC21"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.2 Starting your Program </H2>
<!--docid::SEC20::-->
<P>
<DL COMPACT>
<A NAME="IDX91"></A>
<A NAME="IDX92"></A>
<DT><CODE>run</CODE>
<DD><DT><CODE>r</CODE>
<DD>Use the <CODE>run</CODE> command to start your program under GDB.
You must first specify the program name (except on VxWorks) with an
argument to GDB (see section <A HREF="gdb_3.html#SEC6">Getting In and Out of GDB</A>), or by using the <CODE>file</CODE> or <CODE>exec-file</CODE> command
(see section <A HREF="gdb_16.html#SEC155">Commands to Specify Files</A>).
<P>
</DL>
<P>
If you are running your program in an execution environment that
supports processes, <CODE>run</CODE> creates an inferior process and makes
that process run your program. (In environments without processes,
<CODE>run</CODE> jumps to the start of your program.)
</P><P>
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 <EM>before</EM> 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:
</P><P>
<DL COMPACT>
<DT>The <EM>arguments.</EM>
<DD>Specify the arguments to give your program as the arguments of the
<CODE>run</CODE> 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
<CODE>SHELL</CODE> environment variable.
See section <A HREF="gdb_5.html#SEC21">Your Program's Arguments</A>.
<P>
<DT>The <EM>environment.</EM>
<DD>Your program normally inherits its environment from GDB, but you can
use the GDB commands <CODE>set environment</CODE> and <CODE>unset
environment</CODE> to change parts of the environment that affect
your program. See section <A HREF="gdb_5.html#SEC22">Your Program's Environment</A>.
<P>
<DT>The <EM>working directory.</EM>
<DD>Your program inherits its working directory from GDB. You can set
the GDB working directory with the <CODE>cd</CODE> command in GDB.
See section <A HREF="gdb_5.html#SEC23">Your Program's Working Directory</A>.
<P>
<DT>The <EM>standard input and output.</EM>
<DD>Your program normally uses the same device for standard input and
standard output as GDB is using. You can redirect input and output
in the <CODE>run</CODE> command line, or you can use the <CODE>tty</CODE> command to
set a different device for your program.
See section <A HREF="gdb_5.html#SEC24">Your Program's Input and Output</A>.
<P>
<A NAME="IDX93"></A>
<EM>Warning:</EM> 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.
</DL>
<P>
When you issue the <CODE>run</CODE> command, your program begins to execute
immediately. See section <A HREF="gdb_6.html#SEC31">Stopping and Continuing</A>, 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 <CODE>print</CODE>
or <CODE>call</CODE> commands. See section <A HREF="gdb_9.html#SEC59">Examining Data</A>.
</P><P>
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.
</P><P>
<DL COMPACT>
<A NAME="IDX94"></A>
<DT><CODE>start</CODE>
<DD><A NAME="IDX95"></A>
The name of the main procedure can vary from language to language.
With C or C<TT>++</TT>, the main procedure name is always <CODE>main</CODE>, 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.
<P>
The <SAMP>`start'</SAMP> command does the equivalent of setting a temporary
breakpoint at the beginning of the main procedure and then invoking
the <SAMP>`run'</SAMP> command.
</P><P>
<A NAME="IDX96"></A>
Some programs contain an <EM>elaboration</EM> 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<TT>++</TT>, for instance,
constructors for static and global objects are executed before
<CODE>main</CODE> is called. It is therefore possible that the debugger stops
before reaching the main procedure. However, the temporary breakpoint
will remain to halt execution.
</P><P>
Specify the arguments to give to your program as arguments to the
<SAMP>`start'</SAMP> command. These arguments will be given verbatim to the
underlying <SAMP>`run'</SAMP> command. Note that the same arguments will be
reused if no argument is provided during subsequent calls to
<SAMP>`start'</SAMP> or <SAMP>`run'</SAMP>.
</P><P>
It is sometimes necessary to debug the program during elaboration. In
these cases, using the <CODE>start</CODE> 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.
</DL>
<P>
<A NAME="Arguments"></A>
<HR SIZE="6">
<A NAME="SEC21"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC20"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC22"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC22"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.3 Your Program's Arguments </H2>
<!--docid::SEC21::-->
<P>
<A NAME="IDX97"></A>
The arguments to your program can be specified by the arguments of the
<CODE>run</CODE> command.
They are passed to a shell, which expands wildcard characters and
performs redirection of I/O, and thence to your program. Your
<CODE>SHELL</CODE> environment variable (if it exists) specifies what shell
GDB uses. If you do not define <CODE>SHELL</CODE>, GDB uses
the default shell (<TT>`/bin/sh'</TT> on Unix).
</P><P>
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.
</P><P>
<CODE>run</CODE> with no arguments uses the same arguments used by the previous
<CODE>run</CODE>, or those set by the <CODE>set args</CODE> command.
</P><P>
<DL COMPACT>
<A NAME="IDX98"></A>
<DT><CODE>set args</CODE>
<DD>Specify the arguments to be used the next time your program is run. If
<CODE>set args</CODE> has no arguments, <CODE>run</CODE> executes your program
with no arguments. Once you have run your program with arguments,
using <CODE>set args</CODE> before the next <CODE>run</CODE> is the only way to run
it again without arguments.
<P>
<A NAME="IDX99"></A>
<DT><CODE>show args</CODE>
<DD>Show the arguments to give your program when it is started.
</DL>
<P>
<A NAME="Environment"></A>
<HR SIZE="6">
<A NAME="SEC22"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC21"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC23"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC23"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.4 Your Program's Environment </H2>
<!--docid::SEC22::-->
<P>
<A NAME="IDX100"></A>
The <EM>environment</EM> 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.
</P><P>
<DL COMPACT>
<A NAME="IDX101"></A>
<DT><CODE>path <VAR>directory</VAR></CODE>
<DD>Add <VAR>directory</VAR> to the front of the <CODE>PATH</CODE> environment variable
(the search path for executables) that will be passed to your program.
The value of <CODE>PATH</CODE> used by GDB does not change.
You may specify several directory names, separated by whitespace or by a
system-dependent separator character (<SAMP>`:'</SAMP> on Unix, <SAMP>`;'</SAMP> on
MS-DOS and MS-Windows). If <VAR>directory</VAR> is already in the path, it
is moved to the front, so it is searched sooner.
<P>
You can use the string <SAMP>`$cwd'</SAMP> to refer to whatever is the current
working directory at the time GDB searches the path. If you
use <SAMP>`.'</SAMP> instead, it refers to the directory where you executed the
<CODE>path</CODE> command. GDB replaces <SAMP>`.'</SAMP> in the
<VAR>directory</VAR> argument (with the current path) before adding
<VAR>directory</VAR> to the search path.
</P><P>
<A NAME="IDX102"></A>
<DT><CODE>show paths</CODE>
<DD>Display the list of search paths for executables (the <CODE>PATH</CODE>
environment variable).
<P>
<A NAME="IDX103"></A>
<DT><CODE>show environment [<VAR>varname</VAR>]</CODE>
<DD>Print the value of environment variable <VAR>varname</VAR> to be given to
your program when it starts. If you do not supply <VAR>varname</VAR>,
print the names and values of all environment variables to be given to
your program. You can abbreviate <CODE>environment</CODE> as <CODE>env</CODE>.
<P>
<A NAME="IDX104"></A>
<DT><CODE>set environment <VAR>varname</VAR> [=<VAR>value</VAR>]</CODE>
<DD>Set environment variable <VAR>varname</VAR> to <VAR>value</VAR>. The value
changes for your program only, not for GDB itself. <VAR>value</VAR> may
be any string; the values of environment variables are just strings, and
any interpretation is supplied by your program itself. The <VAR>value</VAR>
parameter is optional; if it is eliminated, the variable is set to a
null value.
<P>
For example, this command:
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>set env USER = foo
</FONT></pre></td></tr></table></P><P>
tells the debugged program, when subsequently run, that its user is named
<SAMP>`foo'</SAMP>. (The spaces around <SAMP>`='</SAMP> are used for clarity here; they
are not actually required.)
</P><P>
<A NAME="IDX105"></A>
<DT><CODE>unset environment <VAR>varname</VAR></CODE>
<DD>Remove variable <VAR>varname</VAR> from the environment to be passed to your
program. This is different from <SAMP>`set env <VAR>varname</VAR> ='</SAMP>;
<CODE>unset environment</CODE> removes the variable from the environment,
rather than assigning it an empty value.
</DL>
<P>
<EM>Warning:</EM> On Unix systems, GDB runs your program using
the shell indicated
by your <CODE>SHELL</CODE> environment variable if it exists (or
<CODE>/bin/sh</CODE> if not). If your <CODE>SHELL</CODE> variable names a shell
that runs an initialization file--such as <TT>`.cshrc'</TT> for C-shell, or
<TT>`.bashrc'</TT> 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 <TT>`.login'</TT> or
<TT>`.profile'</TT>.
</P><P>
<A NAME="Working Directory"></A>
<HR SIZE="6">
<A NAME="SEC23"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC22"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC24"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC24"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.5 Your Program's Working Directory </H2>
<!--docid::SEC23::-->
<P>
<A NAME="IDX106"></A>
Each time you start your program with <CODE>run</CODE>, 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 <CODE>cd</CODE> command.
</P><P>
The GDB working directory also serves as a default for the commands
that specify files for GDB to operate on. See section <A HREF="gdb_16.html#SEC155">Commands to Specify Files</A>.
</P><P>
<DL COMPACT>
<A NAME="IDX107"></A>
<A NAME="IDX108"></A>
<DT><CODE>cd <VAR>directory</VAR></CODE>
<DD>Set the GDB working directory to <VAR>directory</VAR>.
<P>
<A NAME="IDX109"></A>
<DT><CODE>pwd</CODE>
<DD>Print the GDB working directory.
</DL>
<P>
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 <TT>`/proc'</TT> support, you can use the <CODE>info
proc</CODE> command (see section <A HREF="gdb_19.html#SEC181">18.1.3 SVR4 Process Information</A>) to find out the
current working directory of the debuggee.
</P><P>
<A NAME="Input/Output"></A>
<HR SIZE="6">
<A NAME="SEC24"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC23"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC25"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC25"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.6 Your Program's Input and Output </H2>
<!--docid::SEC24::-->
<P>
<A NAME="IDX110"></A>
<A NAME="IDX111"></A>
<A NAME="IDX112"></A>
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.
</P><P>
<DL COMPACT>
<A NAME="IDX113"></A>
<DT><CODE>info terminal</CODE>
<DD>Displays information recorded by GDB about the terminal modes your
program is using.
</DL>
<P>
You can redirect your program's input and/or output using shell
redirection with the <CODE>run</CODE> command. For example,
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>run &#62; outfile
</FONT></pre></td></tr></table></P><P>
starts your program, diverting its output to the file <TT>`outfile'</TT>.
</P><P>
<A NAME="IDX114"></A>
<A NAME="IDX115"></A>
Another way to specify where your program should do input and output is
with the <CODE>tty</CODE> command. This command accepts a file name as
argument, and causes this file to be the default for future <CODE>run</CODE>
commands. It also resets the controlling terminal for the child
process, for future <CODE>run</CODE> commands. For example,
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>tty /dev/ttyb
</FONT></pre></td></tr></table></P><P>
directs that processes started with subsequent <CODE>run</CODE> commands
default to do input and output on the terminal <TT>`/dev/ttyb'</TT> and have
that as their controlling terminal.
</P><P>
An explicit redirection in <CODE>run</CODE> overrides the <CODE>tty</CODE> command's
effect on the input/output device, but not its effect on the controlling
terminal.
</P><P>
When you use the <CODE>tty</CODE> command or redirect input in the <CODE>run</CODE>
command, only the input <EM>for your program</EM> is affected. The input
for GDB still comes from your terminal. <CODE>tty</CODE> is an alias
for <CODE>set inferior-tty</CODE>.
</P><P>
<A NAME="IDX116"></A>
<A NAME="IDX117"></A>
You can use the <CODE>show inferior-tty</CODE> command to tell GDB to
display the name of the terminal that will be used for future runs of your
program.
</P><P>
<DL COMPACT>
<DT><CODE>set inferior-tty /dev/ttyb</CODE>
<DD><A NAME="IDX118"></A>
Set the tty for the program being debugged to /dev/ttyb.
<P>
<DT><CODE>show inferior-tty</CODE>
<DD><A NAME="IDX119"></A>
Show the current tty for the program being debugged.
</DL>
<P>
<A NAME="Attach"></A>
<HR SIZE="6">
<A NAME="SEC25"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC24"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC26"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC26"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.7 Debugging an Already-running Process </H2>
<!--docid::SEC25::-->
<P>
<DL COMPACT>
<DT><CODE>attach <VAR>process-id</VAR></CODE>
<DD>This command attaches to a running process--one that was started
outside GDB. (<CODE>info files</CODE> shows your active
targets.) The command takes as argument a process ID. The usual way to
find out the <VAR>process-id</VAR> of a Unix process is with the <CODE>ps</CODE> utility,
or with the <SAMP>`jobs -l'</SAMP> shell command.
<P>
<CODE>attach</CODE> does not repeat if you press <KBD>RET</KBD> a second time after
executing the command.
</DL>
<P>
To use <CODE>attach</CODE>, your program must be running in an environment
which supports processes; for example, <CODE>attach</CODE> 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.
</P><P>
When you use <CODE>attach</CODE>, 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 <A HREF="gdb_8.html#SEC57">Specifying Source Directories</A>). You can also use
the <CODE>file</CODE> command to load the program. See section <A HREF="gdb_16.html#SEC155">Commands to Specify Files</A>.
</P><P>
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 <CODE>run</CODE>. 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 <CODE>continue</CODE> command after
attaching GDB to the process.
</P><P>
<DL COMPACT>
<A NAME="IDX120"></A>
<DT><CODE>detach</CODE>
<DD>When you have finished debugging the attached process, you can use the
<CODE>detach</CODE> command to release it from GDB control. Detaching
the process continues its execution. After the <CODE>detach</CODE> command,
that process and GDB become completely independent once more, and you
are ready to <CODE>attach</CODE> another process or start one with <CODE>run</CODE>.
<CODE>detach</CODE> does not repeat if you press <KBD>RET</KBD> again after
executing the command.
</DL>
<P>
If you exit GDB while you have an attached process, you detach
that process. If you use the <CODE>run</CODE> 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
<CODE>set confirm</CODE> command (see section <A HREF="gdb_20.html#SEC227">Optional Warnings and Messages</A>).
</P><P>
<A NAME="Kill Process"></A>
<HR SIZE="6">
<A NAME="SEC26"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC25"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC27"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC27"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.8 Killing the Child Process </H2>
<!--docid::SEC26::-->
<P>
<DL COMPACT>
<A NAME="IDX121"></A>
<DT><CODE>kill</CODE>
<DD>Kill the child process in which your program is running under GDB.
</DL>
<P>
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.
</P><P>
On some operating systems, a program cannot be executed outside GDB
while you have breakpoints set on it inside GDB. You can use the
<CODE>kill</CODE> command in this situation to permit running your program
outside the debugger.
</P><P>
The <CODE>kill</CODE> 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 <CODE>run</CODE>, GDB notices that the file has changed, and
reads the symbol table again (while trying to preserve your current
breakpoint settings).
</P><P>
<A NAME="Threads"></A>
<HR SIZE="6">
<A NAME="SEC27"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC26"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC28"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.9 Debugging Programs with Multiple Threads </H2>
<!--docid::SEC27::-->
<P>
<A NAME="IDX122"></A>
<A NAME="IDX123"></A>
<A NAME="IDX124"></A>
In some operating systems, such as HP-UX and Solaris, a single program
may have more than one <EM>thread</EM> 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.
</P><P>
GDB provides these facilities for debugging multi-thread
programs:
</P><P>
<UL>
<LI>automatic notification of new threads
<LI><SAMP>`thread <VAR>threadno</VAR>'</SAMP>, a command to switch among threads
<LI><SAMP>`info threads'</SAMP>, a command to inquire about existing threads
<LI><SAMP>`thread apply [<VAR>threadno</VAR>] [<VAR>all</VAR>] <VAR>args</VAR>'</SAMP>,
a command to apply a command to a list of threads
<LI>thread-specific breakpoints
<LI><SAMP>`set print thread-events'</SAMP>, which controls printing of
messages on thread start and exit.
</UL>
<P>
<BLOCKQUOTE>
<EM>Warning:</EM> These facilities are not yet available on every
GDB configuration where the operating system supports threads.
If your GDB does not support threads, these commands have no
effect. For example, a system without thread support shows no output
from <SAMP>`info threads'</SAMP>, and always rejects the <CODE>thread</CODE> command,
like this:
<P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>(gdb) info threads
(gdb) thread 1
Thread ID 1 not known. Use the "info threads" command to
see the IDs of currently known threads.
</FONT></pre></td></tr></table></BLOCKQUOTE>
<P>
<A NAME="IDX125"></A>
<A NAME="IDX126"></A>
The GDB thread debugging facility allows you to 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 <EM>current thread</EM>. Debugging commands show
program information from the perspective of the current thread.
</P><P>
<A NAME="IDX127"></A>
<A NAME="IDX128"></A>
Whenever GDB detects a new thread in your program, it displays
the target system's identification for the thread with a message in the
form <SAMP>`[New <VAR>systag</VAR>]'</SAMP>. <VAR>systag</VAR> is a thread identifier
whose form varies depending on the particular system. For example, on
GNU/Linux, you might see
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>[New Thread 46912507313328 (LWP 25582)]
</FONT></pre></td></tr></table></P><P>
when GDB notices a new thread. In contrast, on an SGI system,
the <VAR>systag</VAR> is simply something like <SAMP>`process 368'</SAMP>, with no
further qualifier.
</P><P>
<A NAME="IDX129"></A>
<A NAME="IDX130"></A>
For debugging purposes, GDB associates its own thread
number--always a single integer--with each thread in your program.
</P><P>
<DL COMPACT>
<A NAME="IDX131"></A>
<DT><CODE>info threads</CODE>
<DD>Display a summary of all threads currently in your
program. GDB displays for each thread (in this order):
<P>
<OL>
<LI>
the thread number assigned by GDB
<P>
<LI>
the target system's thread identifier (<VAR>systag</VAR>)
<P>
<LI>
the current stack frame summary for that thread
</OL>
<P>
An asterisk <SAMP>`*'</SAMP> to the left of the GDB thread number
indicates the current thread.
</P><P>
For example,
</DL>
<P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>(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
</FONT></pre></td></tr></table></P><P>
On HP-UX systems:
</P><P>
<A NAME="IDX132"></A>
<A NAME="IDX133"></A>
For debugging purposes, GDB associates its own thread
number--a small integer assigned in thread-creation order--with each
thread in your program.
</P><P>
<A NAME="IDX134"></A>
<A NAME="IDX135"></A>
Whenever GDB detects a new thread in your program, it displays
both GDB's thread number and the target system's identification for the thread with a message in the
form <SAMP>`[New <VAR>systag</VAR>]'</SAMP>. <VAR>systag</VAR> is a thread identifier
whose form varies depending on the particular system. For example, on
HP-UX, you see
</P><P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>[New thread 2 (system thread 26594)]
</FONT></pre></td></tr></table></P><P>
when GDB notices a new thread.
</P><P>
<DL COMPACT>
<A NAME="IDX136"></A>
<DT><CODE>info threads</CODE>
<DD>Display a summary of all threads currently in your
program. GDB displays for each thread (in this order):
<P>
<OL>
<LI>the thread number assigned by GDB
<P>
<LI>the target system's thread identifier (<VAR>systag</VAR>)
<P>
<LI>the current stack frame summary for that thread
</OL>
<P>
An asterisk <SAMP>`*'</SAMP> to the left of the GDB thread number
indicates the current thread.
</P><P>
For example,
</DL>
<P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>(gdb) info threads
* 3 system thread 26607 worker (wptr=0x7b09c318 "@") \<BR>
at quicksort.c:137
2 system thread 26606 0x7b0030d8 in __ksleep () \<BR>
from /usr/lib/libc.2
1 system thread 27905 0x7b003498 in _brk () \<BR>
from /usr/lib/libc.2
</FONT></pre></td></tr></table></P><P>
On Solaris, you can display more information about user threads with a
Solaris-specific command:
</P><P>
<DL COMPACT>
<DT><CODE>maint info sol-threads</CODE>
<DD><A NAME="IDX137"></A>
<A NAME="IDX138"></A>
Display info on Solaris user threads.
</DL>
<P>
<DL COMPACT>
<A NAME="IDX139"></A>
<DT><CODE>thread <VAR>threadno</VAR></CODE>
<DD>Make thread number <VAR>threadno</VAR> the current thread. The command
argument <VAR>threadno</VAR> is the internal GDB thread number, as
shown in the first field of the <SAMP>`info threads'</SAMP> display.
GDB responds by displaying the system identifier of the thread
you selected, and its current stack frame summary:
<P>
<TABLE><tr><td>&nbsp;</td><td class=smallexample><FONT SIZE=-1><pre>(gdb) thread 2
[Switching to process 35 thread 23]
0x34e5 in sigpause ()
</FONT></pre></td></tr></table></P><P>
As with the <SAMP>`[New <small>...</small>]'</SAMP> message, the form of the text after
<SAMP>`Switching to'</SAMP> depends on your system's conventions for identifying
threads.
</P><P>
<A NAME="IDX140"></A>
<A NAME="IDX141"></A>
<DT><CODE>thread apply [<VAR>threadno</VAR>] [<VAR>all</VAR>] <VAR>command</VAR></CODE>
<DD>The <CODE>thread apply</CODE> command allows you to apply the named
<VAR>command</VAR> to one or more threads. Specify the numbers of the
threads that you want affected with the command argument
<VAR>threadno</VAR>. It can be a single thread number, one of the numbers
shown in the first field of the <SAMP>`info threads'</SAMP> display; or it
could be a range of thread numbers, as in <CODE>2-4</CODE>. To apply a
command to all threads, type <KBD>thread apply all <VAR>command</VAR></KBD>.
<P>
<A NAME="IDX142"></A>
<A NAME="IDX143"></A>
<DT><CODE>set print thread-events</CODE>
<DD><DT><CODE>set print thread-events on</CODE>
<DD><DT><CODE>set print thread-events off</CODE>
<DD>The <CODE>set print thread-events</CODE> command allows you to enable or
disable printing of messages when GDB notices that new threads have
started or that threads have exited. By default, these messages will
be printed if detection of these events is supported by the target.
Note that these messages cannot be disabled on all targets.
<P>
<A NAME="IDX144"></A>
<DT><CODE>show print thread-events</CODE>
<DD>Show whether messages will be printed when GDB detects that threads
have started and exited.
</DL>
<P>
<A NAME="IDX145"></A>
<A NAME="IDX146"></A>
<A NAME="IDX147"></A>
Whenever GDB stops your program, due to 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 <SAMP>`[Switching to <VAR>systag</VAR>]'</SAMP> to identify the
thread.
</P><P>
See section <A HREF="gdb_6.html#SEC45">Stopping and Starting Multi-thread Programs</A>, for
more information about how GDB behaves when you stop and start
programs with multiple threads.
</P><P>
See section <A HREF="gdb_6.html#SEC34">Setting Watchpoints</A>, for information about
watchpoints in programs with multiple threads.
</P><P>
<A NAME="Processes"></A>
<HR SIZE="6">
<A NAME="SEC28"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC27"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC29"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC20"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.10 Debugging Programs with Multiple Processes </H2>
<!--docid::SEC28::-->
<P>
<A NAME="IDX148"></A>
<A NAME="IDX149"></A>
<A NAME="IDX150"></A>
On most systems, GDB has no special support for debugging
programs which create additional processes using the <CODE>fork</CODE>
function. When a program forks, GDB will continue to debug the
parent process and the child process will run unimpeded. If you have
set a breakpoint in any code which the child then executes, the child
will get a <CODE>SIGTRAP</CODE> signal which (unless it catches the signal)
will cause it to terminate.
</P><P>
However, if you want to debug the child process there is a workaround
which isn't too painful. Put a call to <CODE>sleep</CODE> in the code which
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 need not occur when you don't want to run GDB
on the child. While the child is sleeping, use the <CODE>ps</CODE> program to
get its process ID. Then tell GDB (a new invocation of
GDB if you are also debugging the parent process) to attach to
the child process (see section <A HREF="gdb_5.html#SEC25">4.7 Debugging an Already-running Process</A>). From that point on you can debug
the child process just like any other process which you attached to.
</P><P>
On some systems, GDB provides support for debugging programs that
create additional processes using the <CODE>fork</CODE> or <CODE>vfork</CODE> functions.
Currently, the only platforms with this feature are HP-UX (11.x and later
only?) and GNU/Linux (kernel version 2.5.60 and later).
</P><P>
By default, when a program forks, GDB will continue to debug
the parent process and the child process will run unimpeded.
</P><P>
If you want to follow the child process instead of the parent process,
use the command <CODE>set follow-fork-mode</CODE>.
</P><P>
<DL COMPACT>
<A NAME="IDX151"></A>
<DT><CODE>set follow-fork-mode <VAR>mode</VAR></CODE>
<DD>Set the debugger response to a program call of <CODE>fork</CODE> or
<CODE>vfork</CODE>. A call to <CODE>fork</CODE> or <CODE>vfork</CODE> creates a new
process. The <VAR>mode</VAR> argument can be:
<P>
<DL COMPACT>
<DT><CODE>parent</CODE>
<DD>The original process is debugged after a fork. The child process runs
unimpeded. This is the default.
<P>
<DT><CODE>child</CODE>
<DD>The new process is debugged after a fork. The parent process runs
unimpeded.
<P>
</DL>
<P>
<A NAME="IDX152"></A>
<DT><CODE>show follow-fork-mode</CODE>
<DD>Display the current debugger response to a <CODE>fork</CODE> or <CODE>vfork</CODE> call.
</DL>
<P>
<A NAME="IDX153"></A>
On Linux, if you want to debug both the parent and child processes, use the
command <CODE>set detach-on-fork</CODE>.
</P><P>
<DL COMPACT>
<A NAME="IDX154"></A>
<DT><CODE>set detach-on-fork <VAR>mode</VAR></CODE>
<DD>Tells gdb whether to detach one of the processes after a fork, or
retain debugger control over them both.
<P>
<DL COMPACT>
<DT><CODE>on</CODE>
<DD>The child process (or parent process, depending on the value of
<CODE>follow-fork-mode</CODE>) will be detached and allowed to run
independently. This is the default.
<P>
<DT><CODE>off</CODE>
<DD>Both processes will be held under the control of GDB.
One process (child or parent, depending on the value of
<CODE>follow-fork-mode</CODE>) is debugged as usual, while the other
is held suspended.
<P>
</DL>
<P>
<A NAME="IDX155"></A>
<DT><CODE>show detach-on-fork</CODE>
<DD>Show whether detach-on-fork mode is on/off.
</DL>
<P>
If you choose to set <SAMP>`detach-on-fork'</SAMP> mode off, then
GDB will retain control of all forked processes (including
nested forks). You can list the forked processes under the control of
GDB by using the <CODE>info forks</CODE> command, and switch
from one fork to another by using the <CODE>fork</CODE> command.
</P><P>
<DL COMPACT>
<A NAME="IDX156"></A>
<DT><CODE>info forks</CODE>
<DD>Print a list of all forked processes under the control of GDB.
The listing will include a fork id, a process id, and the current
position (program counter) of the process.
<P>
<A NAME="IDX157"></A>
<DT><CODE>fork <VAR>fork-id</VAR></CODE>
<DD>Make fork number <VAR>fork-id</VAR> the current process. The argument
<VAR>fork-id</VAR> is the internal fork number assigned by GDB,
as shown in the first field of the <SAMP>`info forks'</SAMP> display.
<P>
<A NAME="IDX158"></A>
<DT><CODE>process <VAR>process-id</VAR></CODE>
<DD>Make process number <VAR>process-id</VAR> the current process. The
argument <VAR>process-id</VAR> must be one that is listed in the output of
<SAMP>`info forks'</SAMP>.
<P>
</DL>
<P>
To quit debugging one of the forked processes, you can either detach
from it by using the <CODE>detach fork</CODE> command (allowing it to
run independently), or delete (and kill) it using the
<CODE>delete fork</CODE> command.
</P><P>
<DL COMPACT>
<A NAME="IDX159"></A>
<DT><CODE>detach fork <VAR>fork-id</VAR></CODE>
<DD>Detach from the process identified by GDB fork number
<VAR>fork-id</VAR>, and remove it from the fork list. The process will be
allowed to run independently.
<P>
<A NAME="IDX160"></A>
<DT><CODE>delete fork <VAR>fork-id</VAR></CODE>
<DD>Kill the process identified by GDB fork number <VAR>fork-id</VAR>,
and remove it from the fork list.
<P>
</DL>
<P>
If you ask to debug a child process and a <CODE>vfork</CODE> is followed by an
<CODE>exec</CODE>, GDB executes the new target up to the first
breakpoint in the new target. If you have a breakpoint set on
<CODE>main</CODE> in your original program, the breakpoint will also be set on
the child process's <CODE>main</CODE>.
</P><P>
When a child process is spawned by <CODE>vfork</CODE>, you cannot debug the
child or parent until an <CODE>exec</CODE> call completes.
</P><P>
If you issue a <CODE>run</CODE> command to GDB after an <CODE>exec</CODE>
call executes, the new target restarts. To restart the parent process,
use the <CODE>file</CODE> command with the parent executable name as its
argument.
</P><P>
You can use the <CODE>catch</CODE> command to make GDB stop whenever
a <CODE>fork</CODE>, <CODE>vfork</CODE>, or <CODE>exec</CODE> call is made. See section <A HREF="gdb_6.html#SEC35">Setting Catchpoints</A>.
</P><P>
<A NAME="Checkpoint/Restart"></A>
<HR SIZE="6">
<A NAME="SEC29"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC28"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC30"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC20"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC18"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H2> 4.11 Setting a <EM>Bookmark</EM> to Return to Later </H2>
<!--docid::SEC29::-->
<P>
<A NAME="IDX161"></A>
<A NAME="IDX162"></A>
<A NAME="IDX163"></A>
<A NAME="IDX164"></A>
<A NAME="IDX165"></A>
</P><P>
On certain operating systems<A NAME="DOCF2" HREF="gdb_fot.html#FOOT2">(2)</A>, GDB is able to save a <EM>snapshot</EM> of a
program's state, called a <EM>checkpoint</EM>, and come back to it
later.
</P><P>
Returning to a checkpoint effectively undoes everything that has
happened in the program since the <CODE>checkpoint</CODE> was saved. This
includes changes in memory, registers, and even (within some limits)
system state. Effectively, it is like going back in time to the
moment when the checkpoint was saved.
</P><P>
Thus, if you're stepping thru a program and you think you're
getting close to the point where things go wrong, you can save
a checkpoint. Then, if you accidentally go too far and miss
the critical statement, instead of having to restart your program
from the beginning, you can just go back to the checkpoint and
start again from there.
</P><P>
This can be especially useful if it takes a lot of time or
steps to reach the point where you think the bug occurs.
</P><P>
To use the <CODE>checkpoint</CODE>/<CODE>restart</CODE> method of debugging:
</P><P>
<DL COMPACT>
<A NAME="IDX166"></A>
<DT><CODE>checkpoint</CODE>
<DD>Save a snapshot of the debugged program's current execution state.
The <CODE>checkpoint</CODE> command takes no arguments, but each checkpoint
is assigned a small integer id, similar to a breakpoint id.
<P>
<A NAME="IDX167"></A>
<DT><CODE>info checkpoints</CODE>
<DD>List the checkpoints that have been saved in the current debugging
session. For each checkpoint, the following information will be
listed:
<P>
<DL COMPACT>
<DT><CODE>Checkpoint ID</CODE>
<DD><DT><CODE>Process ID</CODE>
<DD><DT><CODE>Code Address</CODE>
<DD><DT><CODE>Source line, or label</CODE>
<DD></DL>
<P>
<A NAME="IDX168"></A>
<DT><CODE>restart <VAR>checkpoint-id</VAR></CODE>
<DD>Restore the program state that was saved as checkpoint number
<VAR>checkpoint-id</VAR>. All program variables, registers, stack frames
etc. will be returned to the values that they had when the checkpoint
was saved. In essence, gdb will "wind back the clock" to the point
in time when the checkpoint was saved.
<P>
Note that breakpoints, GDB variables, command history etc.
are not affected by restoring a checkpoint. In general, a checkpoint
only restores things that reside in the program being debugged, not in
the debugger.
</P><P>
<A NAME="IDX169"></A>
<DT><CODE>delete checkpoint <VAR>checkpoint-id</VAR></CODE>
<DD>Delete the previously-saved checkpoint identified by <VAR>checkpoint-id</VAR>.
<P>
</DL>
<P>
Returning to a previously saved checkpoint will restore the user state
of the program being debugged, plus a significant subset of the system
(OS) state, including file pointers. It won't "un-write" data from
a file, but it will rewind the file pointer to the previous location,
so that the previously written data can be overwritten. For files
opened in read mode, the pointer will also be restored so that the
previously read data can be read again.
</P><P>
Of course, characters that have been sent to a printer (or other
external device) cannot be "snatched back", and characters received
from eg. a serial device can be removed from internal program buffers,
but they cannot be "pushed back" into the serial pipeline, ready to
be received again. Similarly, the actual contents of files that have
been changed cannot be restored (at this time).
</P><P>
However, within those constraints, you actually can "rewind" your
program to a previously saved point in time, and begin debugging it
again -- and you can change the course of events so as to debug a
different execution path this time.
</P><P>
<A NAME="IDX170"></A>
Finally, there is one bit of internal program state that will be
different when you return to a checkpoint -- the program's process
id. Each checkpoint will have a unique process id (or <VAR>pid</VAR>),
and each will be different from the program's original <VAR>pid</VAR>.
If your program has saved a local copy of its process id, this could
potentially pose a problem.
</P><P>
<HR SIZE="6">
<A NAME="SEC30"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC29"> &lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC20"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC29"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<H3> 4.11.1 A Non-obvious Benefit of Using Checkpoints </H3>
<!--docid::SEC30::-->
<P>
On some systems such as GNU/Linux, address space randomization
is performed on new processes for security reasons. This makes it
difficult or impossible to set a breakpoint, or watchpoint, on an
absolute address if you have to restart the program, since the
absolute location of a symbol will change from one execution to the
next.
</P><P>
A checkpoint, however, is an <EM>identical</EM> copy of a process.
Therefore if you create a checkpoint at (eg.) the start of main,
and simply return to that checkpoint instead of restarting the
process, you can avoid the effects of address randomization and
your symbols will all stay in the same place.
</P><P>
<A NAME="Stopping"></A>
<HR SIZE="6">
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_5.html#SEC20"> &lt;&lt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_6.html#SEC31"> &gt;&gt; </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_38.html#SEC764">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
<address>
<p>Please send FSF &amp; GNU inquiries &amp; questions to <a
href="mailto:gnu@gnu.org">gnu@gnu.org</a>. There are also <a
href="http://www.gnu.org/home.html#ContactInfo">other ways to
contact</a> the FSF.</p>
<p>These pages are maintained by <a
href="http://www.gnu.org/software/gdb/">the GDB developers</a>.</p>
<p>Copyright Free Software Foundation, Inc., 59 Temple Place - Suite
330, Boston, MA 02111, USA.</p>
<p>Verbatim copying and distribution of this entire article is
permitted in any medium, provided this notice is preserved.</p>
</address>
This document was generated
by <I>GDB Administrator</I> on <I>March, 27 2008</I>
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>
View git blame Copy permalink