Next: Enable and Disable Tracepoints, Up: Set Tracepoints

#### 13.1.1 Create and Delete Tracepoints

`trace` location
  The `trace` command is very similar to the `break` command. Its argument location can be a source line, a function name, or an address in the target program. See Specify Location. 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 actions doesn't take effect until the next `tstart` command, and once a trace experiment is running, further changes will not have any effect until the next trace experiment starts.

  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`.

`trace` location `if` cond
  Set a tracepoint with condition cond; evaluate the expression cond each time the tracepoint is reached, and collect data only if the value is nonzero—that is, if cond evaluates as true. See Tracepoint Conditions, for more information on tracepoint conditions.
`ftrace` location`[ if` cond`]`
  The `ftrace` command sets a fast tracepoint. For targets that support them, fast tracepoints will use a more efficient but possibly less general technique to trigger data collection, such as a jump instruction instead of a trap, or some sort of hardware support. It may not be possible to create a fast tracepoint at the desired location, in which case the command will exit with an explanatory message.

  gdb handles arguments to `ftrace` exactly as for `trace`.

`strace` location`[ if` cond`]`
  The `strace` command sets a static tracepoint. For targets that support it, setting a static tracepoint probes a static instrumentation point, or marker, found at location. It may not be possible to set a static tracepoint at the desired location, in which case the command will exit with an explanatory message.

  gdb handles arguments to `strace` exactly as for `trace`, with the addition that the user can also specify `-m` marker as location. This probes the marker identified by the marker string identifier. This identifier depends on the static tracepoint backend library your program is using. You can find all the marker identifiers in the ‘`ID`’ field of the `info static-tracepoint-markers` command output. See Listing Static Tracepoint Markers. For example, in the following small program using the UST tracing engine:

                main ()
                {
                  trace_mark(ust, bar33, "str %s", "FOOBAZ");
                }

  the marker id is composed of joining the first two arguments to the `trace_mark` call with a slash, which translates to:

                (gdb) info static-tracepoint-markers
                Cnt Enb ID         Address            What
                1   n   ust/bar33  0x0000000000400ddc in main at stexample.c:22
                         Data: "str %s"
                [etc...]

  so you may probe the marker above with:

                (gdb) strace -m ust/bar33

  Static tracepoints accept an extra collect action — `collect $_sdata`. This collects arbitrary user data passed in the probe point call to the tracing library. In the UST example above, you'll see that the third argument to `trace_mark` is a printf-like format string. The user data is then the result of running that formating string against the following arguments. Note that `info static-tracepoint-markers` command output lists that format string in the ‘`Data:`’ field.

  You can inspect this data when analyzing the trace buffer, by printing the $_sdata variable like any other variable available to gdb. See Tracepoint Action Lists.

  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. Note that the regular `delete` command can remove tracepoints also.

  Examples:

                (gdb) delete trace 1 2 3 // remove three tracepoints

                (gdb) delete trace       // remove all tracepoints

  You can abbreviate this command as `del tr`.