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.
Using gdb's trace and collect commands, you can
specify locations in the program, called tracepoints, and
arbitrary expressions to evaluate when those tracepoints are reached.
Later, using the tfind 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.
The tracepoint facility is currently available only for remote
targets.
Refer to Chapter 18 Specifying a Debugging Target. 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.
This chapter describes the tracepoint commands and features.
12.1. Commands to Set Tracepoints
Before running such a trace experiment, an arbitrary number of
tracepoints can be set. Like a breakpoint (refer to Section 7.1.1 Setting breakpoints), 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.
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.
This section describes commands to set tracepoints and associated
conditions and actions.
12.1.1. Create and Delete Tracepoints
trace
The trace command is very similar to the break command.
Its argument can be a source line, a function name, or an address in
the target program.
Refer to Section 7.1.1 Setting breakpoints. The trace 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 tstart command; thus, you
cannot change the tracepoint attributes once a trace experiment is
running.
Here are some examples of using the trace command:
(gdb) trace foo.c:121 // a source file and line number
(gdb) trace +2 // 2 lines forward
(gdb) trace my_function // first source line of function
(gdb) trace *my_function // EXACT start address of function
(gdb) trace *0x2117c4 // an address
You can abbreviate trace as tr.
The convenience variable $tpnum records the tracepoint number
of the most recently set tracepoint.
delete tracepoint [num]
Permanently delete one or more tracepoints. With no argument, the
default is to delete all tracepoints.
Examples:
(gdb) delete trace 1 2 3 // remove three tracepoints
(gdb) delete trace // remove all tracepoints
You can abbreviate this command as del tr.
12.1.2. Enable and Disable Tracepoints
disable tracepoint [num]
Disable tracepoint num, or all tracepoints if no argument
num 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 enable tracepoint command.
enable tracepoint [num]
Enable tracepoint num, or all tracepoints. The enabled
tracepoints will become effective the next time a trace experiment is
run.
12.1.3. Tracepoint Passcounts
passcount [n [num]]
Set the passcount of a tracepoint. The passcount is a way to
automatically stop a trace experiment. If a tracepoint's passcount is
n, then the trace experiment will be automatically stopped on
the n'th time that tracepoint is hit. If the tracepoint number
num is not specified, the passcount 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.
Examples:
(gdb) passcount 5 2 // Stop on the 5th execution of
// tracepoint 2
(gdb) passcount 12 // Stop on the 12th execution of the
// most recently defined tracepoint.
(gdb) trace foo
(gdb) pass 3
(gdb) trace bar
(gdb) pass 2
(gdb) trace baz
(gdb) pass 1 // Stop tracing when foo has been
// executed 3 times OR when bar has// been executed 2 times// OR when baz has been executed 1 time.
12.1.4. Tracepoint Action Lists
actions [num]
This command will prompt for a list of actions to be taken when the
tracepoint is hit. If the tracepoint number num 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
actions 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 end. So
far, the only defined actions are collect and
while-stepping.
To remove all actions from a tracepoint, type actions num
and follow it immediately with end.
(gdb) collect data // collect some data
(gdb) while-stepping 5 // single-step 5 times, collect data
(gdb) end // signals the end of actions.
In the following example, the action list begins with collect
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 while-stepping command is used,
followed by the list of things to be collected while stepping. The
while-stepping command is terminated by its own separate
end command. Lastly, the action list is terminated by an
end command.
(gdb) trace foo
(gdb) actions
Enter actions for tracepoint 1, one per line:
> collect bar,baz
> collect $regs
> while-stepping 12
> collect $fp, $sp
> end
end
collect expr1, expr2, …
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:
$regs
collect all registers
$args
collect all function arguments
$locals
collect all local variables.
You can give several consecutive collect commands, each one
with a single argument, or one collect command with several
arguments separated by commas: the effect is the same.
The command info scope (info scope) is
particularly useful for figuring out what data to collect.
while-stepping n
Perform n single-step traces after the tracepoint, collecting
new data at each step. The while-stepping command is
followed by the list of what to collect while stepping (followed by
its own end command):
> while-stepping 12
> collect $regs, myglobal
> end
>
You may abbreviate while-stepping as ws or
stepping.
12.1.5. Listing Tracepoints
info tracepoints [num]
Display information about the tracepoint num. 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:
its number
whether it is enabled or disabled
its address
its passcount as given by the passcount n command
its step count as given by the while-stepping n command
where in the source files is the tracepoint set
its action list as given by the actions command
(gdb) info trace
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)
This command can be abbreviated info tp.
12.1.6. Starting and Stopping Trace Experiment
tstart
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.
tstop
This command takes no arguments. It ends the trace experiment, and
stops collecting data.
Note: a trace experiment and data collection may stop
automatically if any tracepoint's passcount is reached
(refer to Section 12.1.3 Tracepoint Passcounts), or if the trace buffer becomes full.
tstatus
This command displays the status of the current trace data
collection.
Here is an example of the commands we described so far:
(gdb) trace gdb_c_test
(gdb) actions
Enter actions for tracepoint #1, one per line.
> collect $regs,$locals,$args
> while-stepping 11
> collect $regs
> end
> end
(gdb) tstart
[time passes …]
(gdb) tstop
