dbgeng.breakpoint

The breakpoint functions are accessible from the global dbgeng.breakpoint table, and represent the functions from the IDebugBreakpoint interfaces of the dbgeng COM API.

Breakpoints objects are generated from functions in dbgeng.control: add_breakpoint() to create a new breakpoint, and get_breakpoint_by_id() or get_breakpoint_by_index() to retrieve an existing breakpoint.

Breakpoints are removed by calling dbgeng.control.remove_breakpoint() and passing a breakpoint object. They are not removed when the Lua variable goes out of scope or is collected by garbage collection.

All of the breakpoint methods are object methods, which means they can be called using Lua object method syntax. Assuming a variable bp containing a breakpoint object, this call would return the command to be executed when the breakpoint is hit:

local cmd = bp:get_command()

This is really just syntatic sugar for the more verbose:

local cmd = dbgeng.breakpoint.get_command( bp )

Object methods

dbgeng.breakpoint.add_flags(flags) → nil

Adds flags to the breakpoint by combining the given bitfield with existing flags using bitwise OR. Possible flag values can be found in the flag table. See AddFlags.

Parameters:flags (integer) – bitfield, combining values from flag
dbgeng.breakpoint.get_command() → string

Returns the command string that is executed when a breakpoint is triggered. See GetCommand.

dbgeng.breakpoint.get_current_pass_count() → integer

Returns the remaining number of times that the target must reach the breakpoint location before the breakpoint is triggered. See GetCurrentPassCount.

dbgeng.breakpoint.get_data_parameters() → integer, integer

Returns two values:

  • The first is the size in bytes of the memory block whose access triggers the breakpoint.
  • The second is the access type, which will equal one of the values from the access table.

See GetDataParameters.

dbgeng.breakpoint.get_flags() → integer

Returns the flags for a breakpoint, as a bitfield, combining values from the flag table. See GetFlags.

dbgeng.breakpoint.get_id() → integer

Returns the breakpoint’s id. See GetId.

dbgeng.breakpoint.get_match_thread_id() → integer or nil

If a thread has been set for the breakpoint, the breakpoint can be triggered only if that thread hits the breakpoint. If a thread has not been set, any thread can trigger the breakpoint.

Returns the engine thread id that can trigger the breakpoint, or nil if a thread has not been set. See GetMatchThreadId.

dbgeng.breakpoint.get_offset() → integer

Returns the location that triggers the breakpoint. See GetOffset.

dbgeng.breakpoint.get_offset_expression() → string

Returns the expression that evaluates to the location that triggers the breakpoint. See GetOffsetExpression.

dbgeng.breakpoint.get_parameters() → table

Returns most parameter information for a breakpoint in one call, rather than using separate calls for each piece. See GetParameters.

Returns:table with the following named fields:
  • offset : location in the target’s memory that will trigger the breakpoint
  • id : breakpoint id
  • break_type : one of the values from the type table
  • proc_type : type of processor the breakpoint is set for
  • flags : breakpoint flags
  • data_size : for a data breakpoint, the size in bytes of the memory location that will trigger the breakpoint; otherwise, zero
  • data_access_type : for a data breakpoint, one of the values from the access table; otherwise, zero
  • pass_count : number of times the target will hit the breakpoint before it triggers
  • current_pass_count : remaining number of times the target will hit the breakpoint before it triggers
  • match_thread : engine thread id of the thread that can trigger the breakpoint; if any thread can trigger it, dbgeng.ANY_ID
dbgeng.breakpoint.get_pass_count() → integer

Returns the number of times that the target was originally required to reach the breakpoint location before the breakpoint is triggered. See GetPassCount.

dbgeng.breakpoint.get_type() → integer, integer

Returns two values:

  • type of breakpoint, which can be one of the values in the type table
  • type of processor the breakpoint is set for

See GetType.

dbgeng.breakpoint.remove_flags(flags) → nil

Removes flags from a breakpoint, by combining the complement of the given bitfield with the existing flags, using bitwise AND. Possible flag values can be found in the flag table. See RemoveFlags.

Parameters:flags (integer) – bitfield, combining values from flag
dbgeng.breakpoint.set_command(command) → nil

Sets the command string that is executed when a breakpoint is triggered. See SetCommand.

Parameters:command (string) – command string to execute
dbgeng.breakpoint.set_data_parameters(size, access_type) → nil

Sets parameters for a processor breakpoint. See SetDataParameters.

Parameters:
  • size (integer) – size in bytes of the memory location whose access will trigger the breakpoint
  • access_type (integer) – one of the values from the access table
dbgeng.breakpoint.set_flags(flags) → nil

Sets the flags for a breakpoint. See SetFlags.

Parameters:flags (integer) – bitfield, combining values from the flag table
dbgeng.breakpoint.set_match_thread_id(id) → nil

Sets the engine thread id that can trigger the breakpoint. If a thread has been set, the setting can be removed by passing dbgeng.ANY_ID for the id. See SetMatchThreadId.

Parameters:id (integer) – id of the thread that can trigger the breakpoint
dbgeng.breakpoint.set_offset(offset) → nil

Sets the memory location in the target that triggers the breakpoint. See SetOffset.

Parameters:offset (integer) – location in the target’s memory
dbgeng.breakpoint.set_offset_expression(expression) → nil

Sets the expression string that evaluates to the location that triggers the breakpoint. See SetOffsetExpression.

Parameters:expression (string) – expression that evaluates to a location in the target’s memory
dbgeng.breakpoint.set_pass_count(passes) → nil

Sets the number of times that the target must reach the breakpoint location before the breakpoint is triggered. See SetPassCount.

Parameters:passes (integer) – number of passes to trigger the breakpoint

Other

dbgeng.breakpoint.access

Table containing the access types that processor breakpoints can be defined with.

  • READ : Triggered when the CPU reads or writes memory in the breakpoint’s block.
  • WRITE : Triggered when the CPU writes memory in the breakpoint’s block.
  • EXECUTE : Triggered when the CPU fetches the instruction in the breakpoint’s block.
  • IO : Triggered when the I/O port in the breakpoint’s block is accessed.
dbgeng.breakpoint.flag

Table containing bit-flags that affect breakpoint operation.

  • ENABLED : When set, the breakpoint is enabled. When not set, the breakpoint is disabled.
  • ADDER_ONLY : When set, the breakpoint is a private breakpoint, only visible to the client that added it. Other clients will not be able to query for it, and events will not be sent to other clients. Callbacks related to the breakpoint will only be sent to this client.
  • GO_ONLY : When set, the breakpoint will only be triggered if the target is in unrestricted execution. It will not be triggered when stepping through instructions.
  • ONE_SHOT : When set, the breakpoint will automatically be removed the first time it triggers.
  • DEFERRED : When set, the breakpoint is deferred. The engine sets this flag when a breakpoint is defined using a symbolic expression, and the engine can’t evaluate the expression. Every time a module is loaded or unloaded in the target, the engine will attempt to reevaluate the expression. This flag cannot be modified by any client.
dbgeng.breakpoint.type

Table containing types of breakpoints that can be created.

  • CODE: software breakpoint
  • DATA: processor breakpoint