| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 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.2, 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="prev" 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="prev">Listing Static Tracepoint Markers</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> |
| </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’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’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’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. |
| > collect $regs,$locals,$args |
| > while-stepping 11 |
| > collect $regs |
| > end |
| > end |
| (gdb) <b>tstart</b> |
| [time passes …] |
| (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’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’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 |
| ‘<samp>circular-trace-buffer</samp>’ 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’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’s notes. |
| </p> |
| </dd> |
| <dt><code>show trace-notes</code></dt> |
| <dd><a name="index-show-trace_002dnotes"></a> |
| <p>Show the trace run’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’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’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="prev">Listing Static Tracepoint Markers</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> |
| </div> |
| |
| |
| |
| </body> |
| </html> |
