+@defun InferiorThread.handle ()
+Return the thread object's handle, represented as a Python @code{bytes}
+object. A @code{gdb.Value} representation of the handle may be
+constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is
+the Python @code{bytes} representation of the handle and @var{type} is
+a @code{gdb.Type} for the handle type.
+@end defun
+
+@node Recordings In Python
+@subsubsection Recordings In Python
+@cindex recordings in python
+
+The following recordings-related functions
+(@pxref{Process Record and Replay}) are available in the @code{gdb}
+module:
+
+@defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]})
+Start a recording using the given @var{method} and @var{format}. If
+no @var{format} is given, the default format for the recording method
+is used. If no @var{method} is given, the default method will be used.
+Returns a @code{gdb.Record} object on success. Throw an exception on
+failure.
+
+The following strings can be passed as @var{method}:
+
+@itemize @bullet
+@item
+@code{"full"}
+@item
+@code{"btrace"}: Possible values for @var{format}: @code{"pt"},
+@code{"bts"} or leave out for default format.
+@end itemize
+@end defun
+
+@defun gdb.current_recording ()
+Access a currently running recording. Return a @code{gdb.Record}
+object on success. Return @code{None} if no recording is currently
+active.
+@end defun
+
+@defun gdb.stop_recording ()
+Stop the current recording. Throw an exception if no recording is
+currently active. All record objects become invalid after this call.
+@end defun
+
+A @code{gdb.Record} object has the following attributes:
+
+@defvar Record.method
+A string with the current recording method, e.g.@: @code{full} or
+@code{btrace}.
+@end defvar
+
+@defvar Record.format
+A string with the current recording format, e.g.@: @code{bt}, @code{pts} or
+@code{None}.
+@end defvar
+
+@defvar Record.begin
+A method specific instruction object representing the first instruction
+in this recording.
+@end defvar
+
+@defvar Record.end
+A method specific instruction object representing the current
+instruction, that is not actually part of the recording.
+@end defvar
+
+@defvar Record.replay_position
+The instruction representing the current replay position. If there is
+no replay active, this will be @code{None}.
+@end defvar
+
+@defvar Record.instruction_history
+A list with all recorded instructions.
+@end defvar
+
+@defvar Record.function_call_history
+A list with all recorded function call segments.
+@end defvar
+
+A @code{gdb.Record} object has the following methods:
+
+@defun Record.goto (instruction)
+Move the replay position to the given @var{instruction}.
+@end defun
+
+The common @code{gdb.Instruction} class that recording method specific
+instruction objects inherit from, has the following attributes:
+
+@defvar Instruction.pc
+An integer representing this instruction's address.
+@end defvar
+
+@defvar Instruction.data
+A buffer with the raw instruction data. In Python 3, the return value is a
+@code{memoryview} object.
+@end defvar
+
+@defvar Instruction.decoded
+A human readable string with the disassembled instruction.
+@end defvar
+
+@defvar Instruction.size
+The size of the instruction in bytes.
+@end defvar
+
+Additionally @code{gdb.RecordInstruction} has the following attributes:
+
+@defvar RecordInstruction.number
+An integer identifying this instruction. @code{number} corresponds to
+the numbers seen in @code{record instruction-history}
+(@pxref{Process Record and Replay}).
+@end defvar
+
+@defvar RecordInstruction.sal
+A @code{gdb.Symtab_and_line} object representing the associated symtab
+and line of this instruction. May be @code{None} if no debug information is
+available.
+@end defvar
+
+@defvar RecordInstruction.is_speculative
+A boolean indicating whether the instruction was executed speculatively.
+@end defvar
+
+If an error occured during recording or decoding a recording, this error is
+represented by a @code{gdb.RecordGap} object in the instruction list. It has
+the following attributes:
+
+@defvar RecordGap.number
+An integer identifying this gap. @code{number} corresponds to the numbers seen
+in @code{record instruction-history} (@pxref{Process Record and Replay}).
+@end defvar
+
+@defvar RecordGap.error_code
+A numerical representation of the reason for the gap. The value is specific to
+the current recording method.
+@end defvar
+
+@defvar RecordGap.error_string
+A human readable string with the reason for the gap.
+@end defvar
+
+A @code{gdb.RecordFunctionSegment} object has the following attributes:
+
+@defvar RecordFunctionSegment.number
+An integer identifying this function segment. @code{number} corresponds to
+the numbers seen in @code{record function-call-history}
+(@pxref{Process Record and Replay}).
+@end defvar
+
+@defvar RecordFunctionSegment.symbol
+A @code{gdb.Symbol} object representing the associated symbol. May be
+@code{None} if no debug information is available.
+@end defvar
+
+@defvar RecordFunctionSegment.level
+An integer representing the function call's stack level. May be
+@code{None} if the function call is a gap.
+@end defvar
+
+@defvar RecordFunctionSegment.instructions
+A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects
+associated with this function call.
+@end defvar
+
+@defvar RecordFunctionSegment.up
+A @code{gdb.RecordFunctionSegment} object representing the caller's
+function segment. If the call has not been recorded, this will be the
+function segment to which control returns. If neither the call nor the
+return have been recorded, this will be @code{None}.
+@end defvar
+
+@defvar RecordFunctionSegment.prev
+A @code{gdb.RecordFunctionSegment} object representing the previous
+segment of this function call. May be @code{None}.
+@end defvar
+
+@defvar RecordFunctionSegment.next
+A @code{gdb.RecordFunctionSegment} object representing the next segment of
+this function call. May be @code{None}.
+@end defvar
+
+The following example demonstrates the usage of these objects and
+functions to create a function that will rewind a record to the last
+time a function in a different file was executed. This would typically
+be used to track the execution of user provided callback functions in a
+library which typically are not visible in a back trace.
+
+@smallexample
+def bringback ():
+ rec = gdb.current_recording ()
+ if not rec:
+ return
+
+ insn = rec.instruction_history
+ if len (insn) == 0:
+ return
+
+ try:
+ position = insn.index (rec.replay_position)
+ except:
+ position = -1
+ try:
+ filename = insn[position].sal.symtab.fullname ()
+ except:
+ filename = None
+
+ for i in reversed (insn[:position]):
+ try:
+ current = i.sal.symtab.fullname ()
+ except:
+ current = None
+
+ if filename == current:
+ continue
+
+ rec.goto (i)
+ return
+@end smallexample
+
+Another possible application is to write a function that counts the
+number of code executions in a given line range. This line range can
+contain parts of functions or span across several functions and is not
+limited to be contiguous.
+
+@smallexample
+def countrange (filename, linerange):
+ count = 0
+
+ def filter_only (file_name):
+ for call in gdb.current_recording ().function_call_history:
+ try:
+ if file_name in call.symbol.symtab.fullname ():
+ yield call
+ except:
+ pass
+
+ for c in filter_only (filename):
+ for i in c.instructions:
+ try:
+ if i.sal.line in linerange:
+ count += 1
+ break;
+ except:
+ pass
+
+ return count
+@end smallexample
+