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.
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.
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.
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.
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, or all tracepoints. The enabled tracepoints will become effective the next time a trace experiment is run.
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.
|
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 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:
collect all registers
collect all function arguments
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.
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.
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.
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.
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.
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 |