<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: Tracepoints</TITLE>
<META NAME="description" CONTENT="Debugging with GDB: Tracepoints">
<META NAME="keywords" CONTENT="Debugging with GDB: Tracepoints">
<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="SEC84"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_10.html#SEC83"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC85"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_3.html#SEC6"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb.html#SEC_Top"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_12.html#SEC97"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10. Tracepoints </H1>
<!--docid::SEC84::-->
<P>
<A NAME="IDX523"></A>
In some applications, it is not feasible for the debugger to interrupt
the program's execution long enough for the developer to learn
anything helpful about its behavior. If the program's correctness
depends on its real-time behavior, delays introduced by a debugger
might cause the program to change its behavior drastically, or perhaps
fail, even when the code itself is correct. It is useful to be able
to observe the program's behavior without interrupting it.
</P><P>
Using GDB's <CODE>trace</CODE> and <CODE>collect</CODE> commands, you can
specify locations in the program, called <EM>tracepoints</EM>, and
arbitrary expressions to evaluate when those tracepoints are reached.
Later, using the <CODE>tfind</CODE> command, you can examine the values
those expressions had when the program hit the tracepoints. The
expressions may also denote objects in memory--structures or arrays,
for example--whose values GDB should record; while visiting
a particular tracepoint, you may inspect those objects as if they were
in memory at that moment. However, because GDB records these
values without interacting with you, it can do so quickly and
unobtrusively, hopefully not disturbing the program's behavior.
</P><P>
The tracepoint facility is currently available only for remote
targets. See section <A HREF="gdb_17.html#SEC158">16. Specifying a Debugging Target</A>. In addition, your remote target must know
how to collect trace data. This functionality is implemented in the
remote stub; however, none of the stubs distributed with GDB
support tracepoints as of this writing. The format of the remote
packets used to implement tracepoints are described in <A HREF="gdb_33.html#SEC700">D.6 Tracepoint Packets</A>.
</P><P>
This chapter describes the tracepoint commands and features.
</P><P>
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC85">10.1 Commands to Set Tracepoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC92">10.2 Using the Collected Data</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC96">10.3 Convenience Variables for Tracepoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
</TABLE></BLOCKQUOTE>
<P>
<A NAME="Set Tracepoints"></A>
<HR SIZE="6">
<A NAME="SEC85"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC86"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.1 Commands to Set Tracepoints </H2>
<!--docid::SEC85::-->
<P>
Before running such a <EM>trace experiment</EM>, an arbitrary number of
tracepoints can be set. Like a breakpoint (see section <A HREF="gdb_6.html#SEC33">5.1.1 Setting Breakpoints</A>), a
tracepoint has a number assigned to it by GDB. Like with
breakpoints, tracepoint numbers are successive integers starting from
one. Many of the commands associated with tracepoints take the
tracepoint number as their argument, to identify which tracepoint to
work on.
</P><P>
For each tracepoint, you can specify, in advance, some arbitrary set
of data that you want the target to collect in the trace buffer when
it hits that tracepoint. The collected data can include registers,
local variables, or global data. Later, you can use GDB
commands to examine the values these data had at the time the
tracepoint was hit.
</P><P>
This section describes commands to set tracepoints and associated
conditions and actions.
</P><P>
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC86">10.1.1 Create and Delete Tracepoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC87">10.1.2 Enable and Disable Tracepoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC88">10.1.3 Tracepoint Passcounts</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC89">10.1.4 Tracepoint Action Lists</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC90">10.1.5 Listing Tracepoints</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC91">10.1.6 Starting and Stopping Trace Experiments</A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP"></TD></TR>
</TABLE></BLOCKQUOTE>
<P>
<A NAME="Create and Delete Tracepoints"></A>
<HR SIZE="6">
<A NAME="SEC86"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC85"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC87"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC85"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.1.1 Create and Delete Tracepoints </H3>
<!--docid::SEC86::-->
<P>
<DL COMPACT>
<A NAME="IDX524"></A>
<A NAME="IDX525"></A>
<DT><CODE>trace</CODE>
<DD>The <CODE>trace</CODE> command is very similar to the <CODE>break</CODE> command.
Its argument can be a source line, a function name, or an address in
the target program. See section <A HREF="gdb_6.html#SEC33">5.1.1 Setting Breakpoints</A>. The <CODE>trace</CODE> command
defines a tracepoint, which is a point in the target program where the
debugger will briefly stop, collect some data, and then allow the
program to continue. Setting a tracepoint or changing its commands
doesn't take effect until the next <CODE>tstart</CODE> command; thus, you
cannot change the tracepoint attributes once a trace experiment is
running.
<P>
Here are some examples of using the <CODE>trace</CODE> command:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>trace foo.c:121</B> // a source file and line number
(gdb) <B>trace +2</B> // 2 lines forward
(gdb) <B>trace my_function</B> // first source line of function
(gdb) <B>trace *my_function</B> // EXACT start address of function
(gdb) <B>trace *0x2117c4</B> // an address
</FONT></pre></td></tr></table></P><P>
You can abbreviate <CODE>trace</CODE> as <CODE>tr</CODE>.
</P><P>
<A NAME="IDX526"></A>
<A NAME="IDX527"></A>
<A NAME="IDX528"></A>
<A NAME="IDX529"></A>
The convenience variable <CODE>$tpnum</CODE> records the tracepoint number
of the most recently set tracepoint.
</P><P>
<A NAME="IDX530"></A>
<A NAME="IDX531"></A>
<DT><CODE>delete tracepoint [<VAR>num</VAR>]</CODE>
<DD>Permanently delete one or more tracepoints. With no argument, the
default is to delete all tracepoints.
<P>
Examples:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>delete trace 1 2 3</B> // remove three tracepoints
(gdb) <B>delete trace</B> // remove all tracepoints
</FONT></pre></td></tr></table></P><P>
You can abbreviate this command as <CODE>del tr</CODE>.
</DL>
<P>
<A NAME="Enable and Disable Tracepoints"></A>
<HR SIZE="6">
<A NAME="SEC87"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC86"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC88"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC88"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC85"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.1.2 Enable and Disable Tracepoints </H3>
<!--docid::SEC87::-->
<P>
<DL COMPACT>
<A NAME="IDX532"></A>
<DT><CODE>disable tracepoint [<VAR>num</VAR>]</CODE>
<DD>Disable tracepoint <VAR>num</VAR>, or all tracepoints if no argument
<VAR>num</VAR> is given. A disabled tracepoint will have no effect during
the next trace experiment, but it is not forgotten. You can re-enable
a disabled tracepoint using the <CODE>enable tracepoint</CODE> command.
<P>
<A NAME="IDX533"></A>
<DT><CODE>enable tracepoint [<VAR>num</VAR>]</CODE>
<DD>Enable tracepoint <VAR>num</VAR>, or all tracepoints. The enabled
tracepoints will become effective the next time a trace experiment is
run.
</DL>
<P>
<A NAME="Tracepoint Passcounts"></A>
<HR SIZE="6">
<A NAME="SEC88"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC87"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC89"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC89"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC85"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.1.3 Tracepoint Passcounts </H3>
<!--docid::SEC88::-->
<P>
<DL COMPACT>
<A NAME="IDX534"></A>
<A NAME="IDX535"></A>
<DT><CODE>passcount [<VAR>n</VAR> [<VAR>num</VAR>]]</CODE>
<DD>Set the <EM>passcount</EM> of a tracepoint. The passcount is a way to
automatically stop a trace experiment. If a tracepoint's passcount is
<VAR>n</VAR>, then the trace experiment will be automatically stopped on
the <VAR>n</VAR>'th time that tracepoint is hit. If the tracepoint number
<VAR>num</VAR> is not specified, the <CODE>passcount</CODE> command sets the
passcount of the most recently defined tracepoint. If no passcount is
given, the trace experiment will run until stopped explicitly by the
user.
<P>
Examples:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>passcount 5 2</B> // Stop on the 5th execution of
<CODE>// tracepoint 2</CODE>
(gdb) <B>passcount 12</B> // Stop on the 12th execution of the
<CODE>// most recently defined tracepoint.</CODE>
(gdb) <B>trace foo</B>
(gdb) <B>pass 3</B>
(gdb) <B>trace bar</B>
(gdb) <B>pass 2</B>
(gdb) <B>trace baz</B>
(gdb) <B>pass 1</B> // Stop tracing when foo has been
<CODE>// executed 3 times OR when bar has</CODE>
<CODE>// been executed 2 times</CODE>
<CODE>// OR when baz has been executed 1 time.</CODE>
</FONT></pre></td></tr></table></DL>
<P>
<A NAME="Tracepoint Actions"></A>
<HR SIZE="6">
<A NAME="SEC89"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC88"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC90"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC90"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC85"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.1.4 Tracepoint Action Lists </H3>
<!--docid::SEC89::-->
<P>
<DL COMPACT>
<A NAME="IDX536"></A>
<A NAME="IDX537"></A>
<DT><CODE>actions [<VAR>num</VAR>]</CODE>
<DD>This command will prompt for a list of actions to be taken when the
tracepoint is hit. If the tracepoint number <VAR>num</VAR> is not
specified, this command sets the actions for the one that was most
recently defined (so that you can define a tracepoint and then say
<CODE>actions</CODE> without bothering about its number). You specify the
actions themselves on the following lines, one action at a time, and
terminate the actions list with a line containing just <CODE>end</CODE>. So
far, the only defined actions are <CODE>collect</CODE> and
<CODE>while-stepping</CODE>.
<P>
<A NAME="IDX538"></A>
To remove all actions from a tracepoint, type <SAMP>`actions <VAR>num</VAR>'</SAMP>
and follow it immediately with <SAMP>`end'</SAMP>.
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>collect <VAR>data</VAR></B> // collect some data
(gdb) <B>while-stepping 5</B> // single-step 5 times, collect data
(gdb) <B>end</B> // signals the end of actions.
</FONT></pre></td></tr></table></P><P>
In the following example, the action list begins with <CODE>collect</CODE>
commands indicating the things to be collected when the tracepoint is
hit. Then, in order to single-step and collect additional data
following the tracepoint, a <CODE>while-stepping</CODE> command is used,
followed by the list of things to be collected while stepping. The
<CODE>while-stepping</CODE> command is terminated by its own separate
<CODE>end</CODE> command. Lastly, the action list is terminated by an
<CODE>end</CODE> command.
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>trace foo</B>
(gdb) <B>actions</B>
Enter actions for tracepoint 1, one per line:
> collect bar,baz
> collect $regs
> while-stepping 12
> collect $fp, $sp
> end
end
</FONT></pre></td></tr></table></P><P>
<A NAME="IDX539"></A>
<DT><CODE>collect <VAR>expr1</VAR>, <VAR>expr2</VAR>, <small>...</small></CODE>
<DD>Collect values of the given expressions when the tracepoint is hit.
This command accepts a comma-separated list of any valid expressions.
In addition to global, static, or local variables, the following
special arguments are supported:
<P>
<DL COMPACT>
<DT><CODE>$regs</CODE>
<DD>collect all registers
<P>
<DT><CODE>$args</CODE>
<DD>collect all function arguments
<P>
<DT><CODE>$locals</CODE>
<DD>collect all local variables.
</DL>
<P>
You can give several consecutive <CODE>collect</CODE> commands, each one
with a single argument, or one <CODE>collect</CODE> command with several
arguments separated by commas: the effect is the same.
</P><P>
The command <CODE>info scope</CODE> (see section <A HREF="gdb_14.html#SEC146">info scope</A>) is
particularly useful for figuring out what data to collect.
</P><P>
<A NAME="IDX540"></A>
<DT><CODE>while-stepping <VAR>n</VAR></CODE>
<DD>Perform <VAR>n</VAR> single-step traces after the tracepoint, collecting
new data at each step. The <CODE>while-stepping</CODE> command is
followed by the list of what to collect while stepping (followed by
its own <CODE>end</CODE> command):
<P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>> while-stepping 12
> collect $regs, myglobal
> end
>
</FONT></pre></td></tr></table></P><P>
You may abbreviate <CODE>while-stepping</CODE> as <CODE>ws</CODE> or
<CODE>stepping</CODE>.
</DL>
<P>
<A NAME="Listing Tracepoints"></A>
<HR SIZE="6">
<A NAME="SEC90"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC89"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC91"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC91"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC85"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.1.5 Listing Tracepoints </H3>
<!--docid::SEC90::-->
<P>
<DL COMPACT>
<A NAME="IDX541"></A>
<A NAME="IDX542"></A>
<A NAME="IDX543"></A>
<DT><CODE>info tracepoints [<VAR>num</VAR>]</CODE>
<DD>Display information about the tracepoint <VAR>num</VAR>. If you don't specify
a tracepoint number, displays information about all the tracepoints
defined so far. For each tracepoint, the following information is
shown:
<P>
<UL>
<LI>
its number
<LI>
whether it is enabled or disabled
<LI>
its address
<LI>
its passcount as given by the <CODE>passcount <VAR>n</VAR></CODE> command
<LI>
its step count as given by the <CODE>while-stepping <VAR>n</VAR></CODE> command
<LI>
where in the source files is the tracepoint set
<LI>
its action list as given by the <CODE>actions</CODE> command
</UL>
<P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>info trace</B>
Num Enb Address PassC StepC What
1 y 0x002117c4 0 0 <gdb_asm>
2 y 0x0020dc64 0 0 in g_test at g_test.c:1375
3 y 0x0020b1f4 0 0 in get_data at ../foo.c:41
(gdb)
</FONT></pre></td></tr></table></P><P>
This command can be abbreviated <CODE>info tp</CODE>.
</DL>
<P>
<A NAME="Starting and Stopping Trace Experiments"></A>
<HR SIZE="6">
<A NAME="SEC91"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC90"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC85"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.1.6 Starting and Stopping Trace Experiments </H3>
<!--docid::SEC91::-->
<P>
<DL COMPACT>
<A NAME="IDX544"></A>
<A NAME="IDX545"></A>
<A NAME="IDX546"></A>
<DT><CODE>tstart</CODE>
<DD>This command takes no arguments. It starts the trace experiment, and
begins collecting data. This has the side effect of discarding all
the data collected in the trace buffer during the previous trace
experiment.
<P>
<A NAME="IDX547"></A>
<A NAME="IDX548"></A>
<DT><CODE>tstop</CODE>
<DD>This command takes no arguments. It ends the trace experiment, and
stops collecting data.
<P>
<STRONG>Note</STRONG>: a trace experiment and data collection may stop
automatically if any tracepoint's passcount is reached
(see section <A HREF="gdb_11.html#SEC88">10.1.3 Tracepoint Passcounts</A>), or if the trace buffer becomes full.
</P><P>
<A NAME="IDX549"></A>
<A NAME="IDX550"></A>
<A NAME="IDX551"></A>
<DT><CODE>tstatus</CODE>
<DD>This command displays the status of the current trace data
collection.
</DL>
<P>
Here is an example of the commands we described so far:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>trace gdb_c_test</B>
(gdb) <B>actions</B>
Enter actions for tracepoint #1, one per line.
> collect $regs,$locals,$args
> while-stepping 11
> collect $regs
> end
> end
(gdb) <B>tstart</B>
[time passes <small>...</small>]
(gdb) <B>tstop</B>
</FONT></pre></td></tr></table></P><P>
<A NAME="Analyze Collected Data"></A>
<HR SIZE="6">
<A NAME="SEC92"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC91"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC93"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC96"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC96"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.2 Using the Collected Data </H2>
<!--docid::SEC92::-->
<P>
After the tracepoint experiment ends, you use GDB commands
for examining the trace data. The basic idea is that each tracepoint
collects a trace <EM>snapshot</EM> every time it is hit and another
snapshot every time it single-steps. All these snapshots are
consecutively numbered from zero and go into a buffer, and you can
examine them later. The way you examine them is to <EM>focus</EM> on a
specific trace snapshot. When the remote stub is focused on a trace
snapshot, it will respond to all GDB requests for memory and
registers by reading from the buffer which belongs to that snapshot,
rather than from <EM>real</EM> memory or registers of the program being
debugged. This means that <STRONG>all</STRONG> GDB commands
(<CODE>print</CODE>, <CODE>info registers</CODE>, <CODE>backtrace</CODE>, etc.) will
behave as if we were currently debugging the program state as it was
when the tracepoint occurred. Any requests for data that are not in
the buffer will fail.
</P><P>
<BLOCKQUOTE><TABLE BORDER=0 CELLSPACING=0>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC93">10.2.1 <CODE>tfind <VAR>n</VAR></CODE></A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">How to select a trace snapshot</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC94">10.2.2 <CODE>tdump</CODE></A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">How to display all data for a snapshot</TD></TR>
<TR><TD ALIGN="left" VALIGN="TOP"><A HREF="gdb_11.html#SEC95">10.2.3 <CODE>save-tracepoints <VAR>filename</VAR></CODE></A></TD><TD> </TD><TD ALIGN="left" VALIGN="TOP">How to save tracepoints for a future run</TD></TR>
</TABLE></BLOCKQUOTE>
<P>
<A NAME="tfind"></A>
<HR SIZE="6">
<A NAME="SEC93"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC94"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC96"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC96"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.2.1 <CODE>tfind <VAR>n</VAR></CODE> </H3>
<!--docid::SEC93::-->
<P>
<A NAME="IDX552"></A>
<A NAME="IDX553"></A>
<A NAME="IDX554"></A>
The basic command for selecting a trace snapshot from the buffer is
<CODE>tfind <VAR>n</VAR></CODE>, which finds trace snapshot number <VAR>n</VAR>,
counting from zero. If no argument <VAR>n</VAR> is given, the next
snapshot is selected.
</P><P>
Here are the various forms of using the <CODE>tfind</CODE> command.
</P><P>
<DL COMPACT>
<DT><CODE>tfind start</CODE>
<DD>Find the first snapshot in the buffer. This is a synonym for
<CODE>tfind 0</CODE> (since 0 is the number of the first snapshot).
<P>
<DT><CODE>tfind none</CODE>
<DD>Stop debugging trace snapshots, resume <EM>live</EM> debugging.
<P>
<DT><CODE>tfind end</CODE>
<DD>Same as <SAMP>`tfind none'</SAMP>.
<P>
<DT><CODE>tfind</CODE>
<DD>No argument means find the next trace snapshot.
<P>
<DT><CODE>tfind -</CODE>
<DD>Find the previous trace snapshot before the current one. This permits
retracing earlier steps.
<P>
<DT><CODE>tfind tracepoint <VAR>num</VAR></CODE>
<DD>Find the next snapshot associated with tracepoint <VAR>num</VAR>. Search
proceeds forward from the last examined trace snapshot. If no
argument <VAR>num</VAR> is given, it means find the next snapshot collected
for the same tracepoint as the current snapshot.
<P>
<DT><CODE>tfind pc <VAR>addr</VAR></CODE>
<DD>Find the next snapshot associated with the value <VAR>addr</VAR> of the
program counter. Search proceeds forward from the last examined trace
snapshot. If no argument <VAR>addr</VAR> is given, it means find the next
snapshot with the same value of PC as the current snapshot.
<P>
<DT><CODE>tfind outside <VAR>addr1</VAR>, <VAR>addr2</VAR></CODE>
<DD>Find the next snapshot whose PC is outside the given range of
addresses.
<P>
<DT><CODE>tfind range <VAR>addr1</VAR>, <VAR>addr2</VAR></CODE>
<DD>Find the next snapshot whose PC is between <VAR>addr1</VAR> and
<VAR>addr2</VAR>.
<P>
<DT><CODE>tfind line [<VAR>file</VAR>:]<VAR>n</VAR></CODE>
<DD>Find the next snapshot associated with the source line <VAR>n</VAR>. If
the optional argument <VAR>file</VAR> is given, refer to line <VAR>n</VAR> in
that source file. Search proceeds forward from the last examined
trace snapshot. If no argument <VAR>n</VAR> is given, it means find the
next line other than the one currently being examined; thus saying
<CODE>tfind line</CODE> repeatedly can appear to have the same effect as
stepping from line to line in a <EM>live</EM> debugging session.
</DL>
<P>
The default arguments for the <CODE>tfind</CODE> commands are specifically
designed to make it easy to scan through the trace buffer. For
instance, <CODE>tfind</CODE> with no argument selects the next trace
snapshot, and <CODE>tfind -</CODE> with no argument selects the previous
trace snapshot. So, by giving one <CODE>tfind</CODE> command, and then
simply hitting <KBD>RET</KBD> repeatedly you can examine all the trace
snapshots in order. Or, by saying <CODE>tfind -</CODE> and then hitting
<KBD>RET</KBD> repeatedly you can examine the snapshots in reverse order.
The <CODE>tfind line</CODE> command with no argument selects the snapshot
for the next source line executed. The <CODE>tfind pc</CODE> command with
no argument selects the next snapshot with the same program counter
(PC) as the current frame. The <CODE>tfind tracepoint</CODE> command with
no argument selects the next trace snapshot collected by the same
tracepoint as the current one.
</P><P>
In addition to letting you scan through the trace buffer manually,
these commands make it easy to construct GDB scripts that
scan through the trace buffer and print out whatever collected data
you are interested in. Thus, if we want to examine the PC, FP, and SP
registers from each trace frame in the buffer, we can say this:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>tfind start</B>
(gdb) <B>while ($trace_frame != -1)</B>
> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \
$trace_frame, $pc, $sp, $fp
> tfind
> end
Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44
Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44
Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44
Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44
Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44
Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44
Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44
Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44
Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44
Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44
Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14
</FONT></pre></td></tr></table></P><P>
Or, if we want to examine the variable <CODE>X</CODE> at each source line in
the buffer:
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>tfind start</B>
(gdb) <B>while ($trace_frame != -1)</B>
> printf "Frame %d, X == %d\n", $trace_frame, X
> tfind line
> end
Frame 0, X = 1
Frame 7, X = 2
Frame 13, X = 255
</FONT></pre></td></tr></table></P><P>
<A NAME="tdump"></A>
<HR SIZE="6">
<A NAME="SEC94"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC93"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC95"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC95"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC96"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.2.2 <CODE>tdump</CODE> </H3>
<!--docid::SEC94::-->
<P>
This command takes no arguments. It prints all the data collected at
the current trace snapshot.
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>trace 444</B>
(gdb) <B>actions</B>
Enter actions for tracepoint #2, one per line:
> collect $regs, $locals, $args, gdb_long_test
> end
(gdb) <B>tstart</B>
(gdb) <B>tfind line 444</B>
#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66)
at gdb_test.c:444
444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", )
(gdb) <B>tdump</B>
Data collected at tracepoint 2, trace frame 1:
d0 0xc4aa0085 -995491707
d1 0x18 24
d2 0x80 128
d3 0x33 51
d4 0x71aea3d 119204413
d5 0x22 34
d6 0xe0 224
d7 0x380035 3670069
a0 0x19e24a 1696330
a1 0x3000668 50333288
a2 0x100 256
a3 0x322000 3284992
a4 0x3000698 50333336
a5 0x1ad3cc 1758156
fp 0x30bf3c 0x30bf3c
sp 0x30bf34 0x30bf34
ps 0x0 0
pc 0x20b2c8 0x20b2c8
fpcontrol 0x0 0
fpstatus 0x0 0
fpiaddr 0x0 0
p = 0x20e5b4 "gdb-test"
p1 = (void *) 0x11
p2 = (void *) 0x22
p3 = (void *) 0x33
p4 = (void *) 0x44
p5 = (void *) 0x55
p6 = (void *) 0x66
gdb_long_test = 17 '\021'
(gdb)
</FONT></pre></td></tr></table></P><P>
<A NAME="save-tracepoints"></A>
<HR SIZE="6">
<A NAME="SEC95"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC94"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC96"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC96"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC92"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC96"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.2.3 <CODE>save-tracepoints <VAR>filename</VAR></CODE> </H3>
<!--docid::SEC95::-->
<P>
This command saves all current tracepoint definitions together with
their actions and passcounts, into a file <TT>`<VAR>filename</VAR>'</TT>
suitable for use in a later debugging session. To read the saved
tracepoint definitions, use the <CODE>source</CODE> command (see section <A HREF="gdb_21.html#SEC232">20.3 Command Files</A>).
</P><P>
<A NAME="Tracepoint Variables"></A>
<HR SIZE="6">
<A NAME="SEC96"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC95"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_12.html#SEC97"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_12.html#SEC97"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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> 10.3 Convenience Variables for Tracepoints </H2>
<!--docid::SEC96::-->
<P>
<DL COMPACT>
<A NAME="IDX555"></A>
<DT><CODE>(int) $trace_frame</CODE>
<DD>The current trace snapshot (a.k.a. <EM>frame</EM>) number, or -1 if no
snapshot is selected.
<P>
<A NAME="IDX556"></A>
<DT><CODE>(int) $tracepoint</CODE>
<DD>The tracepoint for the current trace snapshot.
<P>
<A NAME="IDX557"></A>
<DT><CODE>(int) $trace_line</CODE>
<DD>The line number for the current trace snapshot.
<P>
<A NAME="IDX558"></A>
<DT><CODE>(char []) $trace_file</CODE>
<DD>The source file for the current trace snapshot.
<P>
<A NAME="IDX559"></A>
<DT><CODE>(char []) $trace_func</CODE>
<DD>The name of the function containing <CODE>$tracepoint</CODE>.
</DL>
<P>
Note: <CODE>$trace_file</CODE> is not suitable for use in <CODE>printf</CODE>,
use <CODE>output</CODE> instead.
</P><P>
Here's a simple example of using these convenience variables for
stepping through all the trace snapshots and printing some of their
data.
</P><P>
<TABLE><tr><td> </td><td class=smallexample><FONT SIZE=-1><pre>(gdb) <B>tfind start</B>
(gdb) <B>while $trace_frame != -1</B>
> output $trace_file
> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint
> tfind
> end
</FONT></pre></td></tr></table></P><P>
<A NAME="Overlays"></A>
<HR SIZE="6">
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_11.html#SEC84"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="gdb_12.html#SEC97"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <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 & GNU inquiries & 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>