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_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 breakpointid
: breakpoint idbreak_type
: one of the values from thetype
tableproc_type
: type of processor the breakpoint is set forflags
: breakpoint flagsdata_size
: for a data breakpoint, the size in bytes of the memory location that will trigger the breakpoint; otherwise, zerodata_access_type
: for a data breakpoint, one of the values from theaccess
table; otherwise, zeropass_count
: number of times the target will hit the breakpoint before it triggerscurrent_pass_count
: remaining number of times the target will hit the breakpoint before it triggersmatch_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.
- type of breakpoint, which can be one of the values in the
-
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 breakpointDATA
: processor breakpoint