doc/gdb/Starting-and-Stopping-Trace-Experiments.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs
Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Debugging with GDB: Starting and Stopping Trace Experiments</title>

<meta name="description" content="Debugging with GDB: Starting and Stopping Trace Experiments">
<meta name="keywords" content="Debugging with GDB: Starting and Stopping Trace Experiments">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Set-Tracepoints.html#Set-Tracepoints" rel="up" title="Set Tracepoints">
<link href="Tracepoint-Restrictions.html#Tracepoint-Restrictions" rel="next" title="Tracepoint Restrictions">
<link href="Listing-Static-Tracepoint-Markers.html#Listing-Static-Tracepoint-Markers" rel="previous" title="Listing Static Tracepoint Markers">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Starting-and-Stopping-Trace-Experiments"></a>
<div class="header">
<p>
Next: <a href="Tracepoint-Restrictions.html#Tracepoint-Restrictions" accesskey="n" rel="next">Tracepoint Restrictions</a>, Previous: <a href="Listing-Static-Tracepoint-Markers.html#Listing-Static-Tracepoint-Markers" accesskey="p" rel="previous">Listing Static Tracepoint Markers</a>, Up: <a href="Set-Tracepoints.html#Set-Tracepoints" accesskey="u" rel="up">Set Tracepoints</a> &nbsp; [<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>
</div>
<hr>
<a name="Starting-and-Stopping-Trace-Experiments-1"></a>
<h4 class="subsection">13.1.9 Starting and Stopping Trace Experiments</h4>

<dl compact="compact">
<dd><a name="index-tstart-_005b-notes-_005d"></a>
<a name="index-start-a-new-trace-experiment"></a>
<a name="index-collected-data-discarded"></a>
</dd>
<dt><code>tstart</code></dt>
<dd><p>This command starts the trace experiment, and begins collecting data.
It has the side effect of discarding all the data collected in the
trace buffer during the previous trace experiment.  If any arguments
are supplied, they are taken as a note and stored with the trace
experiment&rsquo;s state.  The notes may be arbitrary text, and are
especially useful with disconnected tracing in a multi-user context;
the notes can explain what the trace is doing, supply user contact
information, and so forth.
</p>
<a name="index-tstop-_005b-notes-_005d"></a>
<a name="index-stop-a-running-trace-experiment"></a>
</dd>
<dt><code>tstop</code></dt>
<dd><p>This command stops the trace experiment.  If any arguments are
supplied, they are recorded with the experiment as a note.  This is
useful if you are stopping a trace started by someone else, for
instance if the trace is interfering with the system&rsquo;s behavior and
needs to be stopped quickly.
</p>
<p><strong>Note</strong>: a trace experiment and data collection may stop
automatically if any tracepoint&rsquo;s passcount is reached
(see <a href="Tracepoint-Passcounts.html#Tracepoint-Passcounts">Tracepoint Passcounts</a>), or if the trace buffer becomes full.
</p>
<a name="index-tstatus"></a>
<a name="index-status-of-trace-data-collection"></a>
<a name="index-trace-experiment_002c-status-of"></a>
</dd>
<dt><code>tstatus</code></dt>
<dd><p>This command displays the status of the current trace data
collection.
</p></dd>
</dl>

<p>Here is an example of the commands we described so far:
</p>
<div class="smallexample">
<pre class="smallexample">(gdb) <b>trace gdb_c_test</b>
(gdb) <b>actions</b>
Enter actions for tracepoint #1, one per line.
&gt; collect $regs,$locals,$args
&gt; while-stepping 11
  &gt; collect $regs
  &gt; end
&gt; end
(gdb) <b>tstart</b>
	[time passes &hellip;]
(gdb) <b>tstop</b>
</pre></div>

<a name="disconnected-tracing"></a><a name="index-disconnected-tracing"></a>
<p>You can choose to continue running the trace experiment even if
<small>GDB</small> disconnects from the target, voluntarily or
involuntarily.  For commands such as <code>detach</code>, the debugger will
ask what you want to do with the trace.  But for unexpected
terminations (<small>GDB</small> crash, network outage), it would be
unfortunate to lose hard-won trace data, so the variable
<code>disconnected-tracing</code> lets you decide whether the trace should
continue running without <small>GDB</small>.
</p>
<dl compact="compact">
<dt><code>set disconnected-tracing on</code></dt>
<dt><code>set disconnected-tracing off</code></dt>
<dd><a name="index-set-disconnected_002dtracing"></a>
<p>Choose whether a tracing run should continue to run if <small>GDB</small>
has disconnected from the target.  Note that <code>detach</code> or
<code>quit</code> will ask you directly what to do about a running trace no
matter what this variable&rsquo;s setting, so the variable is mainly useful
for handling unexpected situations, such as loss of the network.
</p>
</dd>
<dt><code>show disconnected-tracing</code></dt>
<dd><a name="index-show-disconnected_002dtracing"></a>
<p>Show the current choice for disconnected tracing.
</p>
</dd>
</dl>

<p>When you reconnect to the target, the trace experiment may or may not
still be running; it might have filled the trace buffer in the
meantime, or stopped for one of the other reasons.  If it is running,
it will continue after reconnection.
</p>
<p>Upon reconnection, the target will upload information about the
tracepoints in effect.  <small>GDB</small> will then compare that
information to the set of tracepoints currently defined, and attempt
to match them up, allowing for the possibility that the numbers may
have changed due to creation and deletion in the meantime.  If one of
the target&rsquo;s tracepoints does not match any in <small>GDB</small>, the
debugger will create a new tracepoint, so that you have a number with
which to specify that tracepoint.  This matching-up process is
necessarily heuristic, and it may result in useless tracepoints being
created; you may simply delete them if they are of no use.
</p>
<a name="index-circular-trace-buffer"></a>
<p>If your target agent supports a <em>circular trace buffer</em>, then you
can run a trace experiment indefinitely without filling the trace
buffer; when space runs out, the agent deletes already-collected trace
frames, oldest first, until there is enough room to continue
collecting.  This is especially useful if your tracepoints are being
hit too often, and your trace gets terminated prematurely because the
buffer is full.  To ask for a circular trace buffer, simply set
&lsquo;<samp>circular-trace-buffer</samp>&rsquo; to on.  You can set this at any time,
including during tracing; if the agent can do it, it will change
buffer handling on the fly, otherwise it will not take effect until
the next run.
</p>
<dl compact="compact">
<dt><code>set circular-trace-buffer on</code></dt>
<dt><code>set circular-trace-buffer off</code></dt>
<dd><a name="index-set-circular_002dtrace_002dbuffer"></a>
<p>Choose whether a tracing run should use a linear or circular buffer
for trace data.  A linear buffer will not lose any trace data, but may
fill up prematurely, while a circular buffer will discard old trace
data, but it will have always room for the latest tracepoint hits.
</p>
</dd>
<dt><code>show circular-trace-buffer</code></dt>
<dd><a name="index-show-circular_002dtrace_002dbuffer"></a>
<p>Show the current choice for the trace buffer.  Note that this may not
match the agent&rsquo;s current buffer handling, nor is it guaranteed to
match the setting that might have been in effect during a past run,
for instance if you are looking at frames from a trace file.
</p>
</dd>
</dl>

<dl compact="compact">
<dt><code>set trace-buffer-size <var>n</var></code></dt>
<dt><code>set trace-buffer-size unlimited</code></dt>
<dd><a name="index-set-trace_002dbuffer_002dsize"></a>
<p>Request that the target use a trace buffer of <var>n</var> bytes.  Not all
targets will honor the request; they may have a compiled-in size for
the trace buffer, or some other limitation.  Set to a value of
<code>unlimited</code> or <code>-1</code> to let the target use whatever size it
likes.  This is also the default.
</p>
</dd>
<dt><code>show trace-buffer-size</code></dt>
<dd><a name="index-show-trace_002dbuffer_002dsize"></a>
<p>Show the current requested size for the trace buffer.  Note that this
will only match the actual size if the target supports size-setting,
and was able to handle the requested size.  For instance, if the
target can only change buffer size between runs, this variable will
not reflect the change until the next run starts.  Use <code>tstatus</code>
to get a report of the actual buffer size.
</p></dd>
</dl>

<dl compact="compact">
<dt><code>set trace-user <var>text</var></code></dt>
<dd><a name="index-set-trace_002duser"></a>

</dd>
<dt><code>show trace-user</code></dt>
<dd><a name="index-show-trace_002duser"></a>

</dd>
<dt><code>set trace-notes <var>text</var></code></dt>
<dd><a name="index-set-trace_002dnotes"></a>
<p>Set the trace run&rsquo;s notes.
</p>
</dd>
<dt><code>show trace-notes</code></dt>
<dd><a name="index-show-trace_002dnotes"></a>
<p>Show the trace run&rsquo;s notes.
</p>
</dd>
<dt><code>set trace-stop-notes <var>text</var></code></dt>
<dd><a name="index-set-trace_002dstop_002dnotes"></a>
<p>Set the trace run&rsquo;s stop notes.  The handling of the note is as for
<code>tstop</code> arguments; the set command is convenient way to fix a
stop note that is mistaken or incomplete.
</p>
</dd>
<dt><code>show trace-stop-notes</code></dt>
<dd><a name="index-show-trace_002dstop_002dnotes"></a>
<p>Show the trace run&rsquo;s stop notes.
</p>
</dd>
</dl>

<hr>
<div class="header">
<p>
Next: <a href="Tracepoint-Restrictions.html#Tracepoint-Restrictions" accesskey="n" rel="next">Tracepoint Restrictions</a>, Previous: <a href="Listing-Static-Tracepoint-Markers.html#Listing-Static-Tracepoint-Markers" accesskey="p" rel="previous">Listing Static Tracepoint Markers</a>, Up: <a href="Set-Tracepoints.html#Set-Tracepoints" accesskey="u" rel="up">Set Tracepoints</a> &nbsp; [<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>
</div>


</body>
</html>