1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Create and Delete Tracepoints</title> 18 19<meta name="description" content="Debugging with GDB: Create and Delete Tracepoints"> 20<meta name="keywords" content="Debugging with GDB: Create and Delete Tracepoints"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Set-Tracepoints.html#Set-Tracepoints" rel="up" title="Set Tracepoints"> 29<link href="Enable-and-Disable-Tracepoints.html#Enable-and-Disable-Tracepoints" rel="next" title="Enable and Disable Tracepoints"> 30<link href="Set-Tracepoints.html#Set-Tracepoints" rel="previous" title="Set Tracepoints"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Create-and-Delete-Tracepoints"></a> 65<div class="header"> 66<p> 67Next: <a href="Enable-and-Disable-Tracepoints.html#Enable-and-Disable-Tracepoints" accesskey="n" rel="next">Enable and Disable Tracepoints</a>, Up: <a href="Set-Tracepoints.html#Set-Tracepoints" accesskey="u" rel="up">Set Tracepoints</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Create-and-Delete-Tracepoints-1"></a> 71<h4 class="subsection">13.1.1 Create and Delete Tracepoints</h4> 72 73<dl compact="compact"> 74<dd><a name="index-set-tracepoint"></a> 75<a name="index-trace"></a> 76</dd> 77<dt><code>trace <var>location</var></code></dt> 78<dd><p>The <code>trace</code> command is very similar to the <code>break</code> command. 79Its argument <var>location</var> can be any valid location. 80See <a href="Specify-Location.html#Specify-Location">Specify Location</a>. The <code>trace</code> command defines a tracepoint, 81which is a point in the target program where the debugger will briefly stop, 82collect some data, and then allow the program to continue. Setting a tracepoint 83or changing its actions takes effect immediately if the remote stub 84supports the ‘<samp>InstallInTrace</samp>’ feature (see <a href="General-Query-Packets.html#install-tracepoint-in-tracing">install tracepoint in tracing</a>). 85If remote stub doesn’t support the ‘<samp>InstallInTrace</samp>’ feature, all 86these changes don’t take effect until the next <code>tstart</code> 87command, and once a trace experiment is running, further changes will 88not have any effect until the next trace experiment starts. In addition, 89<small>GDB</small> supports <em>pending tracepoints</em>—tracepoints whose 90address is not yet resolved. (This is similar to pending breakpoints.) 91Pending tracepoints are not downloaded to the target and not installed 92until they are resolved. The resolution of pending tracepoints requires 93<small>GDB</small> support—when debugging with the remote target, and 94<small>GDB</small> disconnects from the remote stub (see <a href="Starting-and-Stopping-Trace-Experiments.html#disconnected-tracing">disconnected tracing</a>), pending tracepoints can not be resolved (and downloaded to 95the remote stub) while <small>GDB</small> is disconnected. 96</p> 97<p>Here are some examples of using the <code>trace</code> command: 98</p> 99<div class="smallexample"> 100<pre class="smallexample">(gdb) <b>trace foo.c:121</b> // a source file and line number 101 102(gdb) <b>trace +2</b> // 2 lines forward 103 104(gdb) <b>trace my_function</b> // first source line of function 105 106(gdb) <b>trace *my_function</b> // EXACT start address of function 107 108(gdb) <b>trace *0x2117c4</b> // an address 109</pre></div> 110 111<p>You can abbreviate <code>trace</code> as <code>tr</code>. 112</p> 113</dd> 114<dt><code>trace <var>location</var> if <var>cond</var></code></dt> 115<dd><p>Set a tracepoint with condition <var>cond</var>; evaluate the expression 116<var>cond</var> each time the tracepoint is reached, and collect data only 117if the value is nonzero—that is, if <var>cond</var> evaluates as true. 118See <a href="Tracepoint-Conditions.html#Tracepoint-Conditions">Tracepoint Conditions</a>, for more 119information on tracepoint conditions. 120</p> 121</dd> 122<dt><code>ftrace <var>location</var> [ if <var>cond</var> ]</code></dt> 123<dd><a name="index-set-fast-tracepoint"></a> 124<a name="index-fast-tracepoints_002c-setting"></a> 125<a name="index-ftrace"></a> 126<p>The <code>ftrace</code> command sets a fast tracepoint. For targets that 127support them, fast tracepoints will use a more efficient but possibly 128less general technique to trigger data collection, such as a jump 129instruction instead of a trap, or some sort of hardware support. It 130may not be possible to create a fast tracepoint at the desired 131location, in which case the command will exit with an explanatory 132message. 133</p> 134<p><small>GDB</small> handles arguments to <code>ftrace</code> exactly as for 135<code>trace</code>. 136</p> 137<p>On 32-bit x86-architecture systems, fast tracepoints normally need to 138be placed at an instruction that is 5 bytes or longer, but can be 139placed at 4-byte instructions if the low 64K of memory of the target 140program is available to install trampolines. Some Unix-type systems, 141such as <small>GNU</small>/Linux, exclude low addresses from the program’s 142address space; but for instance with the Linux kernel it is possible 143to let <small>GDB</small> use this area by doing a <code>sysctl</code> command 144to set the <code>mmap_min_addr</code> kernel parameter, as in 145</p> 146<div class="example"> 147<pre class="example">sudo sysctl -w vm.mmap_min_addr=32768 148</pre></div> 149 150<p>which sets the low address to 32K, which leaves plenty of room for 151trampolines. The minimum address should be set to a page boundary. 152</p> 153</dd> 154<dt><code>strace <var>location</var> [ if <var>cond</var> ]</code></dt> 155<dd><a name="index-set-static-tracepoint"></a> 156<a name="index-static-tracepoints_002c-setting"></a> 157<a name="index-probe-static-tracepoint-marker"></a> 158<a name="index-strace"></a> 159<p>The <code>strace</code> command sets a static tracepoint. For targets that 160support it, setting a static tracepoint probes a static 161instrumentation point, or marker, found at <var>location</var>. It may not 162be possible to set a static tracepoint at the desired location, in 163which case the command will exit with an explanatory message. 164</p> 165<p><small>GDB</small> handles arguments to <code>strace</code> exactly as for 166<code>trace</code>, with the addition that the user can also specify 167<code>-m <var>marker</var></code> as <var>location</var>. This probes the marker 168identified by the <var>marker</var> string identifier. This identifier 169depends on the static tracepoint backend library your program is 170using. You can find all the marker identifiers in the ‘<samp>ID</samp>’ field 171of the <code>info static-tracepoint-markers</code> command output. 172See <a href="Listing-Static-Tracepoint-Markers.html#Listing-Static-Tracepoint-Markers">Listing Static Tracepoint 173Markers</a>. For example, in the following small program using the UST 174tracing engine: 175</p> 176<div class="smallexample"> 177<pre class="smallexample">main () 178{ 179 trace_mark(ust, bar33, "str %s", "FOOBAZ"); 180} 181</pre></div> 182 183<p>the marker id is composed of joining the first two arguments to the 184<code>trace_mark</code> call with a slash, which translates to: 185</p> 186<div class="smallexample"> 187<pre class="smallexample">(gdb) info static-tracepoint-markers 188Cnt Enb ID Address What 1891 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 190 Data: "str %s" 191[etc...] 192</pre></div> 193 194<p>so you may probe the marker above with: 195</p> 196<div class="smallexample"> 197<pre class="smallexample">(gdb) strace -m ust/bar33 198</pre></div> 199 200<p>Static tracepoints accept an extra collect action — <code>collect 201$_sdata</code>. This collects arbitrary user data passed in the probe point 202call to the tracing library. In the UST example above, you’ll see 203that the third argument to <code>trace_mark</code> is a printf-like format 204string. The user data is then the result of running that formatting 205string against the following arguments. Note that <code>info 206static-tracepoint-markers</code> command output lists that format string in 207the ‘<samp>Data:</samp>’ field. 208</p> 209<p>You can inspect this data when analyzing the trace buffer, by printing 210the $_sdata variable like any other variable available to 211<small>GDB</small>. See <a href="Tracepoint-Actions.html#Tracepoint-Actions">Tracepoint Action Lists</a>. 212</p> 213<a name="index-_0024tpnum"></a> 214<a name="index-last-tracepoint-number"></a> 215<a name="index-recent-tracepoint-number"></a> 216<a name="index-tracepoint-number"></a> 217<p>The convenience variable <code>$tpnum</code> records the tracepoint number 218of the most recently set tracepoint. 219</p> 220<a name="index-delete-tracepoint"></a> 221<a name="index-tracepoint-deletion"></a> 222</dd> 223<dt><code>delete tracepoint <span class="roman">[</span><var>num</var><span class="roman">]</span></code></dt> 224<dd><p>Permanently delete one or more tracepoints. With no argument, the 225default is to delete all tracepoints. Note that the regular 226<code>delete</code> command can remove tracepoints also. 227</p> 228<p>Examples: 229</p> 230<div class="smallexample"> 231<pre class="smallexample">(gdb) <b>delete trace 1 2 3</b> // remove three tracepoints 232 233(gdb) <b>delete trace</b> // remove all tracepoints 234</pre></div> 235 236<p>You can abbreviate this command as <code>del tr</code>. 237</p></dd> 238</dl> 239 240<hr> 241<div class="header"> 242<p> 243Next: <a href="Enable-and-Disable-Tracepoints.html#Enable-and-Disable-Tracepoints" accesskey="n" rel="next">Enable and Disable Tracepoints</a>, Up: <a href="Set-Tracepoints.html#Set-Tracepoints" accesskey="u" rel="up">Set Tracepoints</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 244</div> 245 246 247 248</body> 249</html> 250