<html lang="en">
<head>
<title>Process Record and Replay - Debugging with GDB</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Debugging with GDB">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="prev" href="Reverse-Execution.html#Reverse-Execution" title="Reverse Execution">
<link rel="next" href="Stack.html#Stack" title="Stack">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
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.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Process-Record-and-Replay"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Stack.html#Stack">Stack</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Reverse-Execution.html#Reverse-Execution">Reverse Execution</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
<hr>
</div>

<h2 class="chapter">7 Recording Inferior's Execution and Replaying It</h2>

<p><a name="index-process-record-and-replay-373"></a><a name="index-recording-inferior_0027s-execution-and-replaying-it-374"></a>
On some platforms, <span class="sc">gdb</span> provides a special <dfn>process record
and replay</dfn> target that can record a log of the process execution, and
replay it later with both forward and reverse execution commands.

   <p><a name="index-replay-mode-375"></a>When this target is in use, if the execution log includes the record
for the next instruction, <span class="sc">gdb</span> will debug in <dfn>replay
mode</dfn>.  In the replay mode, the inferior does not really execute code
instructions.  Instead, all the events that normally happen during
code execution are taken from the execution log.  While code is not
really executed in replay mode, the values of registers (including the
program counter register) and the memory of the inferior are still
changed as they normally would.  Their contents are taken from the
execution log.

   <p><a name="index-record-mode-376"></a>If the record for the next instruction is not in the execution log,
<span class="sc">gdb</span> will debug in <dfn>record mode</dfn>.  In this mode, the
inferior executes normally, and <span class="sc">gdb</span> records the execution log
for future replay.

   <p>The process record and replay target supports reverse execution
(see <a href="Reverse-Execution.html#Reverse-Execution">Reverse Execution</a>), even if the platform on which the
inferior runs does not.  However, the reverse execution is limited in
this case by the range of the instructions recorded in the execution
log.  In other words, reverse execution on platforms that don't
support it directly can only be done in the replay mode.

   <p>When debugging in the reverse direction, <span class="sc">gdb</span> will work in
replay mode as long as the execution log includes the record for the
previous instruction; otherwise, it will work in record mode, if the
platform supports reverse execution, or stop if not.

   <p>For architecture environments that support process record and replay,
<span class="sc">gdb</span> provides the following commands:

     
<a name="index-target-record-377"></a>
<a name="index-record-378"></a>
<a name="index-rec-379"></a>
<dl><dt><code>target record</code><dd>This command starts the process record and replay target.  The process
record and replay target can only debug a process that is already
running.  Therefore, you need first to start the process with the
<kbd>run</kbd> or <kbd>start</kbd> commands, and then start the recording with
the <kbd>target record</kbd> command.

     <p>Both <code>record</code> and <code>rec</code> are aliases of <code>target record</code>.

     <p><a name="index-displaced-stepping_002c-and-process-record-and-replay-380"></a>Displaced stepping (see <a href="Maintenance-Commands.html#Maintenance-Commands">displaced stepping</a>)
will be automatically disabled when process record and replay target
is started.  That's because the process record and replay target
doesn't support displaced stepping.

     <p><a name="index-non_002dstop-mode_002c-and-process-record-and-replay-381"></a><a name="index-asynchronous-execution_002c-and-process-record-and-replay-382"></a>If the inferior is in the non-stop mode (see <a href="Non_002dStop-Mode.html#Non_002dStop-Mode">Non-Stop Mode</a>) or in
the asynchronous execution mode (see <a href="Background-Execution.html#Background-Execution">Background Execution</a>), the
process record and replay target cannot be started because it doesn't
support these two modes.

     <p><a name="index-record-stop-383"></a><a name="index-rec-s-384"></a><br><dt><code>record stop</code><dd>Stop the process record and replay target.  When process record and
replay target stops, the entire execution log will be deleted and the
inferior will either be terminated, or will remain in its final state.

     <p>When you stop the process record and replay target in record mode (at
the end of the execution log), the inferior will be stopped at the
next instruction that would have been recorded.  In other words, if
you record for a while and then stop recording, the inferior process
will be left in the same state as if the recording never happened.

     <p>On the other hand, if the process record and replay target is stopped
while in replay mode (that is, not at the end of the execution log,
but at some earlier point), the inferior process will become &ldquo;live&rdquo;
at that earlier state, and it will then be possible to continue the
usual &ldquo;live&rdquo; debugging of the process from that state.

     <p>When the inferior process exits, or <span class="sc">gdb</span> detaches from it,
process record and replay target will automatically stop itself.

     <p><a name="index-record-save-385"></a><br><dt><code>record save </code><var>filename</var><dd>Save the execution log to a file <samp><var>filename</var></samp>. 
Default filename is <samp><span class="file">gdb_record.</span><var>process_id</var></samp>, where
<var>process_id</var> is the process ID of the inferior.

     <p><a name="index-record-restore-386"></a><br><dt><code>record restore </code><var>filename</var><dd>Restore the execution log from a file <samp><var>filename</var></samp>. 
File must have been created with <code>record save</code>.

     <p><a name="index-set-record-insn_002dnumber_002dmax-387"></a><br><dt><code>set record insn-number-max </code><var>limit</var><dd>Set the limit of instructions to be recorded.  Default value is 200000.

     <p>If <var>limit</var> is a positive number, then <span class="sc">gdb</span> will start
deleting instructions from the log once the number of the record
instructions becomes greater than <var>limit</var>.  For every new recorded
instruction, <span class="sc">gdb</span> will delete the earliest recorded
instruction to keep the number of recorded instructions at the limit. 
(Since deleting recorded instructions loses information, <span class="sc">gdb</span>
lets you control what happens when the limit is reached, by means of
the <code>stop-at-limit</code> option, described below.)

     <p>If <var>limit</var> is zero, <span class="sc">gdb</span> will never delete recorded
instructions from the execution log.  The number of recorded
instructions is unlimited in this case.

     <p><a name="index-show-record-insn_002dnumber_002dmax-388"></a><br><dt><code>show record insn-number-max</code><dd>Show the limit of instructions to be recorded.

     <p><a name="index-set-record-stop_002dat_002dlimit-389"></a><br><dt><code>set record stop-at-limit</code><dd>Control the behavior when the number of recorded instructions reaches
the limit.  If ON (the default), <span class="sc">gdb</span> will stop when the limit
is reached for the first time and ask you whether you want to stop the
inferior or continue running it and recording the execution log.  If
you decide to continue recording, each new recorded instruction will
cause the oldest one to be deleted.

     <p>If this option is OFF, <span class="sc">gdb</span> will automatically delete the
oldest record to make room for each new one, without asking.

     <p><a name="index-show-record-stop_002dat_002dlimit-390"></a><br><dt><code>show record stop-at-limit</code><dd>Show the current setting of <code>stop-at-limit</code>.

     <p><a name="index-set-record-memory_002dquery-391"></a><br><dt><code>set record memory-query</code><dd>Control the behavior when <span class="sc">gdb</span> is unable to record memory
changes caused by an instruction.  If ON, <span class="sc">gdb</span> will query
whether to stop the inferior in that case.

     <p>If this option is OFF (the default), <span class="sc">gdb</span> will automatically
ignore the effect of such instructions on memory.  Later, when
<span class="sc">gdb</span> replays this execution log, it will mark the log of this
instruction as not accessible, and it will not affect the replay
results.

     <p><a name="index-show-record-memory_002dquery-392"></a><br><dt><code>show record memory-query</code><dd>Show the current setting of <code>memory-query</code>.

     <p><a name="index-info-record-393"></a><br><dt><code>info record</code><dd>Show various statistics about the state of process record and its
in-memory execution log buffer, including:

          <ul>
<li>Whether in record mode or replay mode. 
<li>Lowest recorded instruction number (counting from when the current execution log started recording instructions). 
<li>Highest recorded instruction number. 
<li>Current instruction about to be replayed (if in replay mode). 
<li>Number of instructions contained in the execution log. 
<li>Maximum number of instructions that may be contained in the execution log. 
</ul>

     <p><a name="index-record-delete-394"></a><a name="index-rec-del-395"></a><br><dt><code>record delete</code><dd>When record target runs in replay mode (&ldquo;in the past&rdquo;), delete the
subsequent execution log and begin to record a new execution log starting
from the current address.  This means you will abandon the previously
recorded &ldquo;future&rdquo; and begin recording a new &ldquo;future&rdquo;. 
</dl>

   </body></html>