Next: Stack, Previous: Reverse Execution, Up: Top

## 7 Recording Inferior's Execution and Replaying It

On some platforms, gdb provides a special process record and replay target that can record a log of the process execution, and replay it later with both forward and reverse execution commands.

When this target is in use, if the execution log includes the record for the next instruction, gdb will debug in replay mode. 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.

If the record for the next instruction is not in the execution log, gdb will debug in record mode. In this mode, the inferior executes normally, and gdb records the execution log for future replay.

The process record and replay target supports reverse execution (see Reverse Execution), 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.

When debugging in the reverse direction, gdb 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.

For architecture environments that support process record and replay, gdb provides the following commands:

`record` method
  This command starts the process record and replay target. The recording method can be specified as parameter. Without a parameter the command uses the `full` recording method. The following recording methods are available:
  `full`
    Full record/replay recording using gdb's software record and replay implementation. This method allows replaying and reverse execution.
  `btrace`
    Hardware-supported instruction recording. This method does not allow replaying and reverse execution.

    This recording method may not be available on all processors.

  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 `run` or `start` commands, and then start the recording with the `record` method command.

  Both `record` method and `rec` method are aliases of `target record-`method.

  Displaced stepping (see displaced stepping) 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.

  If the inferior is in the non-stop mode (see Non-Stop Mode) or in the asynchronous execution mode (see Background Execution), not all recording methods are available. The `full` recording method does not support these two modes.

`record stop`
  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.

  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.

  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 “live” at that earlier state, and it will then be possible to continue the usual “live” debugging of the process from that state.

  When the inferior process exits, or gdb detaches from it, process record and replay target will automatically stop itself.

`record save` filename
  Save the execution log to a file `filename`. Default filename is `gdb_record.process_id`, where process_id is the process ID of the inferior.

  This command may not be available for all recording methods.

`record restore` filename
  Restore the execution log from a file `filename`. File must have been created with `record save`.

`set record full insn-number-max` limit
  Set the limit of instructions to be recorded for the `full` recording method. Default value is 200000.

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

  If limit is zero, gdb will never delete recorded instructions from the execution log. The number of recorded instructions is unlimited in this case.

`show record full insn-number-max`
  Show the limit of instructions to be recorded with the `full` recording method.
`set record full stop-at-limit`
  Control the behavior of the `full` recording method when the number of recorded instructions reaches the limit. If ON (the default), gdb 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.

  If this option is OFF, gdb will automatically delete the oldest record to make room for each new one, without asking.

`show record full stop-at-limit`
  Show the current setting of `stop-at-limit`.
`set record full memory-query`
  Control the behavior when gdb is unable to record memory changes caused by an instruction for the `full` recording method. If ON, gdb will query whether to stop the inferior in that case.

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

`show record full memory-query`
  Show the current setting of `memory-query`.

`info record`
  Show various statistics about the recording depending on the recording method:
  `full`
    For the `full` recording method, it shows the state of process record and its in-memory execution log buffer, including:
    - Whether in record mode or replay mode.
    - Lowest recorded instruction number (counting from when the current execution log started recording instructions).
    - Highest recorded instruction number.
    - Current instruction about to be replayed (if in replay mode).
    - Number of instructions contained in the execution log.
    - Maximum number of instructions that may be contained in the execution log.
  `btrace`
    For the `btrace` recording method, it shows the number of instructions that have been recorded and the number of blocks of sequential control-flow that is formed by the recorded instructions.

`record delete`
  When record target runs in replay mode (“in the past”), 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 “future” and begin recording a new “future”.

`record instruction-history`
  Disassembles instructions from the recorded execution log. By default, ten instructions are disassembled. This can be changed using the `set record instruction-history-size` command. Instructions are printed in execution order. There are several ways to specify what part of the execution log to disassemble:
  `record instruction-history` insn
    Disassembles ten instructions starting from instruction number insn.
  `record instruction-history` insn`, +/-`n
    Disassembles n instructions around instruction number insn. If n is preceded with `+`, disassembles n instructions after instruction number insn. If n is preceded with `-`, disassembles n instructions before instruction number insn.
  `record instruction-history`
    Disassembles ten more instructions after the last disassembly.
  `record instruction-history -`
    Disassembles ten more instructions before the last disassembly.
  `record instruction-history` begin end
    Disassembles instructions beginning with instruction number begin until instruction number end. The instruction number end is not included.

  This command may not be available for all recording methods.

`set record instruction-history-size`
  Define how many instructions to disassemble in the `record instruction-history` command. The default value is 10.

`show record instruction-history-size`
  Show how many instructions to disassemble in the `record instruction-history` command.

`record function-call-history`
  Prints the execution history at function granularity. It prints one line for each sequence of instructions that belong to the same function giving the name of that function, the source lines for this instruction sequence (if the `/l` modifier is specified), and the instructions numbers that form the sequence (if the `/i` modifier is specified).

                (gdb) list 1, 10
                1   void foo (void)
                2   {
                3   }
                4
                5   void bar (void)
                6   {
                7     ...
                8     foo ();
                9     ...
                10  }
                (gdb) record function-call-history /l
                1  foo.c:6-8   bar
                2  foo.c:2-3   foo
                3  foo.c:9-10  bar

  By default, ten lines are printed. This can be changed using the `set record function-call-history-size` command. Functions are printed in execution order. There are several ways to specify what to print:

  `record function-call-history` func
    Prints ten functions starting from function number func.
  `record function-call-history` func`, +/-`n
    Prints n functions around function number func. If n is preceded with `+`, prints n functions after function number func. If n is preceded with `-`, prints n functions before function number func.
  `record function-call-history`
    Prints ten more functions after the last ten-line print.
  `record function-call-history -`
    Prints ten more functions before the last ten-line print.
  `record function-call-history` begin end
    Prints functions beginning with function number begin until function number end. The function number end is not included.

  This command may not be available for all recording methods.

`set record function-call-history-size`
  Define how many lines to print in the `record function-call-history` command. The default value is 10.
`show record function-call-history-size`
  Show how many lines to print in the `record function-call-history` command.