Next: , Previous: , Up: Python API   [Contents][Index]


23.2.2.19 Recordings In Python

The following recordings-related functions (see Process Record and Replay) are available in the gdb module:

Function: gdb.start_recording ([method], [format])

Start a recording using the given method and format. If no format is given, the default format for the recording method is used. If no method is given, the default method will be used. Returns a gdb.Record object on success. Throw an exception on failure.

The following strings can be passed as method:

Function: gdb.current_recording ()

Access a currently running recording. Return a gdb.Record object on success. Return None if no recording is currently active.

Function: gdb.stop_recording ()

Stop the current recording. Throw an exception if no recording is currently active. All record objects become invalid after this call.

A gdb.Record object has the following attributes:

Variable: Record.ptid

ID of the thread associated with this object as a tuple of three integers. The first is the Process ID (PID); the second is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID). Either the LWPID or TID may be 0, which indicates that the operating system does not use that identifier.

Variable: Record.method

A string with the current recording method, e.g. full or btrace.

Variable: Record.format

A string with the current recording format, e.g. bt, pts or None.

Variable: Record.begin

A method specific instruction object representing the first instruction in this recording.

Variable: Record.end

A method specific instruction object representing the current instruction, that is not actually part of the recording.

Variable: Record.replay_position

The instruction representing the current replay position. If there is no replay active, this will be None.

Variable: Record.instruction_history

A list with all recorded instructions.

Variable: Record.function_call_history

A list with all recorded function call segments.

A gdb.Record object has the following methods:

Function: Record.goto (instruction)

Move the replay position to the given instruction.

The attributes and methods of instruction objects depend on the current recording method. Currently, only btrace instructions are supported.

A gdb.BtraceInstruction object has the following attributes:

Variable: BtraceInstruction.number

An integer identifying this instruction. number corresponds to the numbers seen in record instruction-history (see Process Record and Replay).

Variable: BtraceInstruction.error

An integer identifying the error code for gaps in the history. None for regular instructions.

Variable: BtraceInstruction.sal

A gdb.Symtab_and_line object representing the associated symtab and line of this instruction. May be None if the instruction is a gap.

Variable: BtraceInstruction.pc

An integer representing this instruction’s address. May be None if the instruction is a gap or the debug symbols could not be read.

Variable: BtraceInstruction.data

A buffer with the raw instruction data. May be None if the instruction is a gap.

Variable: BtraceInstruction.decoded

A human readable string with the disassembled instruction. Contains the error message for gaps.

Variable: BtraceInstruction.size

The size of the instruction in bytes. Will be None if the instruction is a gap.

Variable: BtraceInstruction.is_speculative

A boolean indicating whether the instruction was executed speculatively. Will be None for gaps.

The attributes and methods of function call objects depend on the current recording format. Currently, only btrace function calls are supported.

A gdb.BtraceFunctionCall object has the following attributes:

Variable: BtraceFunctionCall.number

An integer identifying this function call. number corresponds to the numbers seen in record function-call-history (see Process Record and Replay).

Variable: BtraceFunctionCall.symbol

A gdb.Symbol object representing the associated symbol. May be None if the function call is a gap or the debug symbols could not be read.

Variable: BtraceFunctionCall.level

An integer representing the function call’s stack level. May be None if the function call is a gap.

Variable: BtraceFunctionCall.instructions

A list of gdb.BtraceInstruction objects associated with this function call.

Variable: BtraceFunctionCall.up

A gdb.BtraceFunctionCall 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 None.

Variable: BtraceFunctionCall.prev_sibling

A gdb.BtraceFunctionCall object representing the previous segment of this function call. May be None.

Variable: BtraceFunctionCall.next_sibling

A gdb.BtraceFunctionCall object representing the next segment of this function call. May be None.

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.

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

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.

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

Next: , Previous: , Up: Python API   [Contents][Index]