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: Tracepoint Actions</title> 18 19<meta name="description" content="Debugging with GDB: Tracepoint Actions"> 20<meta name="keywords" content="Debugging with GDB: Tracepoint Actions"> 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="Listing-Tracepoints.html#Listing-Tracepoints" rel="next" title="Listing Tracepoints"> 30<link href="Trace-State-Variables.html#Trace-State-Variables" rel="previous" title="Trace State Variables"> 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="Tracepoint-Actions"></a> 65<div class="header"> 66<p> 67Next: <a href="Listing-Tracepoints.html#Listing-Tracepoints" accesskey="n" rel="next">Listing Tracepoints</a>, Previous: <a href="Trace-State-Variables.html#Trace-State-Variables" accesskey="p" rel="previous">Trace State Variables</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="Tracepoint-Action-Lists"></a> 71<h4 class="subsection">13.1.6 Tracepoint Action Lists</h4> 72 73<dl compact="compact"> 74<dd><a name="index-actions"></a> 75<a name="index-tracepoint-actions"></a> 76</dd> 77<dt><code>actions <span class="roman">[</span><var>num</var><span class="roman">]</span></code></dt> 78<dd><p>This command will prompt for a list of actions to be taken when the 79tracepoint is hit. If the tracepoint number <var>num</var> is not 80specified, this command sets the actions for the one that was most 81recently defined (so that you can define a tracepoint and then say 82<code>actions</code> without bothering about its number). You specify the 83actions themselves on the following lines, one action at a time, and 84terminate the actions list with a line containing just <code>end</code>. So 85far, the only defined actions are <code>collect</code>, <code>teval</code>, and 86<code>while-stepping</code>. 87</p> 88<p><code>actions</code> is actually equivalent to <code>commands</code> (see <a href="Break-Commands.html#Break-Commands">Breakpoint Command Lists</a>), except that only the defined 89actions are allowed; any other <small>GDB</small> command is rejected. 90</p> 91<a name="index-remove-actions-from-a-tracepoint"></a> 92<p>To remove all actions from a tracepoint, type ‘<samp>actions <var>num</var></samp>’ 93and follow it immediately with ‘<samp>end</samp>’. 94</p> 95<div class="smallexample"> 96<pre class="smallexample">(gdb) <b>collect <var>data</var></b> // collect some data 97 98(gdb) <b>while-stepping 5</b> // single-step 5 times, collect data 99 100(gdb) <b>end</b> // signals the end of actions. 101</pre></div> 102 103<p>In the following example, the action list begins with <code>collect</code> 104commands indicating the things to be collected when the tracepoint is 105hit. Then, in order to single-step and collect additional data 106following the tracepoint, a <code>while-stepping</code> command is used, 107followed by the list of things to be collected after each step in a 108sequence of single steps. The <code>while-stepping</code> command is 109terminated by its own separate <code>end</code> command. Lastly, the action 110list is terminated by an <code>end</code> command. 111</p> 112<div class="smallexample"> 113<pre class="smallexample">(gdb) <b>trace foo</b> 114(gdb) <b>actions</b> 115Enter actions for tracepoint 1, one per line: 116> collect bar,baz 117> collect $regs 118> while-stepping 12 119 > collect $pc, arr[i] 120 > end 121end 122</pre></div> 123 124<a name="index-collect-_0028tracepoints_0029"></a> 125</dd> 126<dt><code>collect<span class="roman">[</span>/<var>mods</var><span class="roman">]</span> <var>expr1</var>, <var>expr2</var>, …</code></dt> 127<dd><p>Collect values of the given expressions when the tracepoint is hit. 128This command accepts a comma-separated list of any valid expressions. 129In addition to global, static, or local variables, the following 130special arguments are supported: 131</p> 132<dl compact="compact"> 133<dt><code>$regs</code></dt> 134<dd><p>Collect all registers. 135</p> 136</dd> 137<dt><code>$args</code></dt> 138<dd><p>Collect all function arguments. 139</p> 140</dd> 141<dt><code>$locals</code></dt> 142<dd><p>Collect all local variables. 143</p> 144</dd> 145<dt><code>$_ret</code></dt> 146<dd><p>Collect the return address. This is helpful if you want to see more 147of a backtrace. 148</p> 149<p><em>Note:</em> The return address location can not always be reliably 150determined up front, and the wrong address / registers may end up 151collected instead. On some architectures the reliability is higher 152for tracepoints at function entry, while on others it’s the opposite. 153When this happens, backtracing will stop because the return address is 154found unavailable (unless another collect rule happened to match it). 155</p> 156</dd> 157<dt><code>$_probe_argc</code></dt> 158<dd><p>Collects the number of arguments from the static probe at which the 159tracepoint is located. 160See <a href="Static-Probe-Points.html#Static-Probe-Points">Static Probe Points</a>. 161</p> 162</dd> 163<dt><code>$_probe_arg<var>n</var></code></dt> 164<dd><p><var>n</var> is an integer between 0 and 11. Collects the <var>n</var>th argument 165from the static probe at which the tracepoint is located. 166See <a href="Static-Probe-Points.html#Static-Probe-Points">Static Probe Points</a>. 167</p> 168</dd> 169<dt><code>$_sdata</code></dt> 170<dd><a name="index-_0024_005fsdata_002c-collect"></a> 171<p>Collect static tracepoint marker specific data. Only available for 172static tracepoints. See <a href="#Tracepoint-Actions">Tracepoint Action 173Lists</a>. On the UST static tracepoints library backend, an 174instrumentation point resembles a <code>printf</code> function call. The 175tracing library is able to collect user specified data formatted to a 176character string using the format provided by the programmer that 177instrumented the program. Other backends have similar mechanisms. 178Here’s an example of a UST marker call: 179</p> 180<div class="smallexample"> 181<pre class="smallexample"> const char master_name[] = "$your_name"; 182 trace_mark(channel1, marker1, "hello %s", master_name) 183</pre></div> 184 185<p>In this case, collecting <code>$_sdata</code> collects the string 186‘<samp>hello $yourname</samp>’. When analyzing the trace buffer, you can 187inspect ‘<samp>$_sdata</samp>’ like any other variable available to 188<small>GDB</small>. 189</p></dd> 190</dl> 191 192<p>You can give several consecutive <code>collect</code> commands, each one 193with a single argument, or one <code>collect</code> command with several 194arguments separated by commas; the effect is the same. 195</p> 196<p>The optional <var>mods</var> changes the usual handling of the arguments. 197<code>s</code> requests that pointers to chars be handled as strings, in 198particular collecting the contents of the memory being pointed at, up 199to the first zero. The upper bound is by default the value of the 200<code>print elements</code> variable; if <code>s</code> is followed by a decimal 201number, that is the upper bound instead. So for instance 202‘<samp>collect/s25 mystr</samp>’ collects as many as 25 characters at 203‘<samp>mystr</samp>’. 204</p> 205<p>The command <code>info scope</code> (see <a href="Symbols.html#Symbols">info scope</a>) is 206particularly useful for figuring out what data to collect. 207</p> 208<a name="index-teval-_0028tracepoints_0029"></a> 209</dd> 210<dt><code>teval <var>expr1</var>, <var>expr2</var>, …</code></dt> 211<dd><p>Evaluate the given expressions when the tracepoint is hit. This 212command accepts a comma-separated list of expressions. The results 213are discarded, so this is mainly useful for assigning values to trace 214state variables (see <a href="Trace-State-Variables.html#Trace-State-Variables">Trace State Variables</a>) without adding those 215values to the trace buffer, as would be the case if the <code>collect</code> 216action were used. 217</p> 218<a name="index-while_002dstepping-_0028tracepoints_0029"></a> 219</dd> 220<dt><code>while-stepping <var>n</var></code></dt> 221<dd><p>Perform <var>n</var> single-step instruction traces after the tracepoint, 222collecting new data after each step. The <code>while-stepping</code> 223command is followed by the list of what to collect while stepping 224(followed by its own <code>end</code> command): 225</p> 226<div class="smallexample"> 227<pre class="smallexample">> while-stepping 12 228 > collect $regs, myglobal 229 > end 230> 231</pre></div> 232 233<p>Note that <code>$pc</code> is not automatically collected by 234<code>while-stepping</code>; you need to explicitly collect that register if 235you need it. You may abbreviate <code>while-stepping</code> as <code>ws</code> or 236<code>stepping</code>. 237</p> 238</dd> 239<dt><code>set default-collect <var>expr1</var>, <var>expr2</var>, …</code></dt> 240<dd><a name="index-set-default_002dcollect"></a> 241<a name="index-default-collection-action"></a> 242<p>This variable is a list of expressions to collect at each tracepoint 243hit. It is effectively an additional <code>collect</code> action prepended 244to every tracepoint action list. The expressions are parsed 245individually for each tracepoint, so for instance a variable named 246<code>xyz</code> may be interpreted as a global for one tracepoint, and a 247local for another, as appropriate to the tracepoint’s location. 248</p> 249</dd> 250<dt><code>show default-collect</code></dt> 251<dd><a name="index-show-default_002dcollect"></a> 252<p>Show the list of expressions that are collected by default at each 253tracepoint hit. 254</p> 255</dd> 256</dl> 257 258<hr> 259<div class="header"> 260<p> 261Next: <a href="Listing-Tracepoints.html#Listing-Tracepoints" accesskey="n" rel="next">Listing Tracepoints</a>, Previous: <a href="Trace-State-Variables.html#Trace-State-Variables" accesskey="p" rel="previous">Trace State Variables</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> 262</div> 263 264 265 266</body> 267</html> 268