Home       Trees       Indices       Help   
Windows application debugging engine
Package winappdbg :: Module debug :: Class Debug
[hide private]
[frames] | no frames]

Class Debug

The main debugger class.

See Also: http://apps.sourceforge.net/trac/winappdbg/wiki/wiki/Debugging

Instance Methods [hide private]
 
__init__(self, eventHandler=None, bKillOnExit=False)
Debugger object.
 
__del__(self)
 
dont_hook_function(self, pid, address)
Removes a function hook set by hook_function. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
dont_stalk_buffer(self, pid, address, size)
Clears a page breakpoint set by stalk_buffer. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
dont_stalk_function(self, pid, address)
Removes a function hook set by stalk_function. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
dont_stalk_variable(self, tid, address)
Clears a hardware breakpoint set by stalk_variable. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
stalk_buffer(self, pid, address, size, action=None)
Sets a one-shot page breakpoint and notifies when the given buffer is accessed. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
stalk_function(self, pid, address, preCB=None, postCB=None, paramCount=0)
Sets a one-shot function hook at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
stalk_variable(self, tid, address, size, action=None)
Sets a one-shot hardware breakpoint at the given thread, address and size. (Inherited from winappdbg.breakpoint.BreakpointContainer)

Inherited from object: __delattr__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __str__

    Debugging
Process
attach(self, dwProcessId)
Attaches to an existing process for debugging.
 
detach(self, dwProcessId, bIgnoreExceptions=False)
Detaches from a process currently being debugged.
 
detach_from_all(self, bIgnoreExceptions=False)
Detaches from all processes currently being debugged.
Process
execv(self, argv, bConsole=False, bFollow=False, bSuspended=False)
Starts a new process for debugging.
Process
execl(self, lpCmdLine, bConsole=False, bFollow=False, bSuspended=False)
Starts a new process for debugging.
 
clear(self)
Detach from all processes and clean up internal structures.
    Debugging loop
Event
wait(self, dwMilliseconds=None)
Waits for the next debug event and returns an Event object.
 
dispatch(self, event)
Calls the debug event notify callbacks.
 
cont(self, event)
Resumes execution after processing a debug event.
 
loop(self, dwMilliseconds=1000)
Main debugging loop.
int
get_debugee_count(self)
Returns: Number of processes being debugged.
    Event notifications (private)
bool
notify_create_process(self, event)
Notify the creation of a new process.
bool
notify_create_thread(self, event)
Notify the creation of a new thread.
bool
notify_load_dll(self, event)
Notify the load of a new module.
bool
notify_exit_process(self, event)
Notify the termination of a process.
bool
notify_exit_thread(self, event)
Notify the termination of a thread.
bool
notify_unload_dll(self, event)
Notify the unload of a module.
bool
notify_rip(self, event)
Notify of a RIP event.
bool
notify_debug_control_c(self, event)
Notify of a Debug Ctrl-C exception.
bool
notify_ms_vc_exception(self, event)
Notify of a Microsoft Visual C exception.
 
notify_breakpoint(self, event)
Notify breakpoints of a breakpoint exception event. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
notify_guard_page(self, event)
Notify breakpoints of a guard page exception event. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
notify_single_step(self, event)
Notify breakpoints of a single step exception event. (Inherited from winappdbg.breakpoint.BreakpointContainer)
    Simple breakpoint use
 
break_at(self, pid, address, action=None)
Sets a code breakpoint at the given process and address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
dont_break_at(self, pid, address)
Clears a code breakpoint set by break_at. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
dont_stalk_at(self, pid, address)
Clears a code breakpoint set by stalk_at. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
dont_watch_buffer(self, pid, address, size)
Clears a page breakpoint set by watch_buffer. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
dont_watch_variable(self, tid, address)
Clears a hardware breakpoint set by watch_variable. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
hook_function(self, pid, address, preCB=None, postCB=None, paramCount=0)
Sets a function hook at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
stalk_at(self, pid, address, action=None)
Sets a one shot code breakpoint at the given process and address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
unhook_function(self, pid, address)
Removes a function hook set by hook_function. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
watch_buffer(self, pid, address, size, action=None)
Sets a page breakpoint and notifies when the given buffer is accessed. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
watch_variable(self, tid, address, size, action=None)
Sets a hardware breakpoint at the given thread, address and size. (Inherited from winappdbg.breakpoint.BreakpointContainer)
    Symbols
int, None
resolve_exported_function(self, pid, modName, procName)
Resolves the exported DLL function for the given process. (Inherited from winappdbg.breakpoint.BreakpointContainer)
int
resolve_label(self, pid, label)
Resolves a label for the given process. (Inherited from winappdbg.breakpoint.BreakpointContainer)
    Advanced breakpoint use
CodeBreakpoint
define_code_breakpoint(self, dwProcessId, address, condition=True, action=None)
Creates a disabled code breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
HardwareBreakpoint
define_hardware_breakpoint(self, dwThreadId, address, triggerFlag=3, sizeFlag=3, condition=True, action=None)
Creates a disabled hardware breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
PageBreakpoint
define_page_breakpoint(self, dwProcessId, address, pages=1, condition=True, action=None)
Creates a disabled page breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
disable_code_breakpoint(self, dwProcessId, address)
Disables the code breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
disable_hardware_breakpoint(self, dwThreadId, address)
Disables the hardware breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
disable_page_breakpoint(self, dwProcessId, address)
Disables the page breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_code_breakpoint(self, dwProcessId, address)
Enables the code breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_hardware_breakpoint(self, dwThreadId, address)
Enables the hardware breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_one_shot_code_breakpoint(self, dwProcessId, address)
Enables the code breakpoint at the given address for only one shot. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_one_shot_hardware_breakpoint(self, dwThreadId, address)
Enables the hardware breakpoint at the given address for only one shot. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_one_shot_page_breakpoint(self, dwProcessId, address)
Enables the page breakpoint at the given address for only one shot. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_page_breakpoint(self, dwProcessId, address)
Enables the page breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
erase_code_breakpoint(self, dwProcessId, address)
Erases the code breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
erase_hardware_breakpoint(self, dwThreadId, address)
Erases the hardware breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
erase_page_breakpoint(self, dwProcessId, address)
Erases the page breakpoint at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
CodeBreakpoint
get_code_breakpoint(self, dwProcessId, address)
Returns the internally used breakpoint object, for the code breakpoint defined at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
HardwareBreakpoint
get_hardware_breakpoint(self, dwThreadId, address)
Returns the internally used breakpoint object, for the code breakpoint defined at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
PageBreakpoint
get_page_breakpoint(self, dwProcessId, address)
Returns the internally used breakpoint object, for the page breakpoint defined at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
bool
has_code_breakpoint(self, dwProcessId, address)
Checks if a code breakpoint is defined at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
bool
has_hardware_breakpoint(self, dwThreadId, address)
Checks if a hardware breakpoint is defined at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
bool
has_page_breakpoint(self, dwProcessId, address)
Checks if a page breakpoint is defined at the given address. (Inherited from winappdbg.breakpoint.BreakpointContainer)
    Listing breakpoints
list of tuple( pid, tid, bp )
get_all_breakpoints(self)
Returns all breakpoint objects as a list of tuples. (Inherited from winappdbg.breakpoint.BreakpointContainer)
list of tuple( int, CodeBreakpoint )
get_all_code_breakpoints(self)
Returns: All code breakpoints as a list of tuples (pid, bp). (Inherited from winappdbg.breakpoint.BreakpointContainer)
list of tuple( int, HardwareBreakpoint )
get_all_hardware_breakpoints(self)
Returns: All hardware breakpoints as a list of tuples (tid, bp). (Inherited from winappdbg.breakpoint.BreakpointContainer)
list of tuple( int, PageBreakpoint )
get_all_page_breakpoints(self)
Returns: All page breakpoints as a list of tuples (pid, bp). (Inherited from winappdbg.breakpoint.BreakpointContainer)
list of CodeBreakpoint
get_process_code_breakpoints(self, dwProcessId)
Returns: All code breakpoints for the given process. (Inherited from winappdbg.breakpoint.BreakpointContainer)
list of tuple( int, HardwareBreakpoint )
get_process_hardware_breakpoints(self, dwProcessId)
Returns: All hardware breakpoints for each thread in the given process as a list of tuples (tid, bp). (Inherited from winappdbg.breakpoint.BreakpointContainer)
list of PageBreakpoint
get_process_page_breakpoints(self, dwProcessId)
Returns: All page breakpoints for the given process. (Inherited from winappdbg.breakpoint.BreakpointContainer)
list of HardwareBreakpoint
get_thread_hardware_breakpoints(self, dwThreadId)
Returns: All hardware breakpoints for the given thread. (Inherited from winappdbg.breakpoint.BreakpointContainer)
    Batch operations on breakpoints
 
disable_all_breakpoints(self)
Disables all breakpoints in all processes. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
disable_process_breakpoints(self, dwProcessId)
Disables all breakpoints for the given process. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_all_breakpoints(self)
Enables all disabled breakpoints in all processes. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_one_shot_all_breakpoints(self)
Enables for one shot all disabled breakpoints in all processes. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_one_shot_process_breakpoints(self, dwProcessId)
Enables for one shot all disabled breakpoints for the given process. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
enable_process_breakpoints(self, dwProcessId)
Enables all disabled breakpoints for the given process. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
erase_all_breakpoints(self)
Erases all breakpoints in all processes. (Inherited from winappdbg.breakpoint.BreakpointContainer)
 
erase_process_breakpoints(self, dwProcessId)
Erases all breakpoints for the given process. (Inherited from winappdbg.breakpoint.BreakpointContainer)
Class Variables [hide private]
  BP_BREAK_ON_IO_ACCESS = 2 (Inherited from winappdbg.breakpoint.BreakpointContainer)
    Breakpoint types
int BP_TYPE_ANY = 0
To get all breakpoints (Inherited from winappdbg.breakpoint.BreakpointContainer)
int BP_TYPE_CODE = 1
To get code breakpoints only (Inherited from winappdbg.breakpoint.BreakpointContainer)
int BP_TYPE_HARDWARE = 3
To get hardware breakpoints only (Inherited from winappdbg.breakpoint.BreakpointContainer)
int BP_TYPE_PAGE = 2
To get page breakpoints only (Inherited from winappdbg.breakpoint.BreakpointContainer)
    Breakpoint states
int BP_STATE_DISABLED = 0
Breakpoint is disabled. (Inherited from winappdbg.breakpoint.BreakpointContainer)
int BP_STATE_ENABLED = 1
Breakpoint is enabled. (Inherited from winappdbg.breakpoint.BreakpointContainer)
int BP_STATE_ONESHOT = 2
Breakpoint is enabled for one shot. (Inherited from winappdbg.breakpoint.BreakpointContainer)
int BP_STATE_RUNNING = 3
Breakpoint is running (recently hit). (Inherited from winappdbg.breakpoint.BreakpointContainer)
    Memory breakpoint trigger flags
int BP_BREAK_ON_ACCESS = 3
Break on memory read or write. (Inherited from winappdbg.breakpoint.BreakpointContainer)
int BP_BREAK_ON_EXECUTION = 0
Break on code execution. (Inherited from winappdbg.breakpoint.BreakpointContainer)
int BP_BREAK_ON_WRITE = 1
Break on memory write. (Inherited from winappdbg.breakpoint.BreakpointContainer)
    Memory breakpoint size flags
  BP_WATCH_BYTE = 0 (Inherited from winappdbg.breakpoint.BreakpointContainer)
  BP_WATCH_DWORD = 3 (Inherited from winappdbg.breakpoint.BreakpointContainer)
  BP_WATCH_QWORD = 2 (Inherited from winappdbg.breakpoint.BreakpointContainer)
  BP_WATCH_WORD = 1 (Inherited from winappdbg.breakpoint.BreakpointContainer)
Instance Variables [hide private]
System system
A System snapshot that is automatically updated for processes being debugged.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, eventHandler=None, bKillOnExit=False)
(Constructor)

 

Debugger object.

Parameters:
  • eventHandler (EventHandler) - (Optional, recommended) Custom event handler object.
  • bKillOnExit (bool) - (Optional) Global kill on exit mode. True to kill the process on exit, False to detach. Ignored under Windows 2000 and below.
Raises:
  • WindowsError - Raises an exception on error.
Overrides: object.__init__

Note: The eventHandler parameter may be any callable Python object (for example a function, or an instance method). However you'll probably find it more convenient to use an instance of a subclass of EventHandler here.

attach(self, dwProcessId)

 

Attaches to an existing process for debugging.

Parameters:
  • dwProcessId (int) - Global ID of a process to attach to.
Returns: Process
A new Process object.
Decorators:
  • @processidparam
Raises:
  • WindowsError - Raises an exception on error.

See Also: detach, execv, execl

detach(self, dwProcessId, bIgnoreExceptions=False)

 

Detaches from a process currently being debugged.

Parameters:
  • dwProcessId (int) - Global ID of a process to detach from.
  • bIgnoreExceptions (bool) - True to ignore any exceptions that may be raised when detaching.
Decorators:
  • @processidparam
Raises:
  • WindowsError - Raises an exception on error, unless bIgnoreExceptions is True.

See Also: attach, detach_from_all

detach_from_all(self, bIgnoreExceptions=False)

 

Detaches from all processes currently being debugged.

Parameters:
  • bIgnoreExceptions (bool) - True to ignore any exceptions that may be raised when detaching.
Raises:
  • WindowsError - Raises an exception on error, unless bIgnoreExceptions is True.

See Also: attach, detach

execv(self, argv, bConsole=False, bFollow=False, bSuspended=False)

 

Starts a new process for debugging.

This method uses a list of arguments. To use a command line string instead, use execl.

Parameters:
  • argv (list( str... )) - List of command line arguments to pass to the debugee. The first element must be the debugee executable filename.
  • bConsole (bool) - True to inherit the console of the debugger.
  • bFollow (bool) - True to automatically attach to child processes.
  • bSuspended (bool) - True to suspend the main thread before any code is executed in the debugee.
Returns: Process
A new Process object.
Raises:
  • WindowsError - Raises an exception on error.

See Also: attach, detach

execl(self, lpCmdLine, bConsole=False, bFollow=False, bSuspended=False)

 

Starts a new process for debugging.

This method uses a command line string. To use a list of arguments instead, use execv.

Parameters:
  • lpCmdLine (str) - Command line string to execute. The first token must be the debugee executable filename. Tokens with spaces must be enclosed in double quotes. Tokens including double quote characters must be escaped with a backslash.
  • bConsole (bool) - True to inherit the console of the debugger.
  • bFollow (bool) - True to automatically attach to child processes.
  • bSuspended (bool) - True to suspend the main thread before any code is executed in the debugee.
Returns: Process
A new Process object.
Raises:
  • WindowsError - Raises an exception on error.

See Also: attach, detach

wait(self, dwMilliseconds=None)

 

Waits for the next debug event and returns an Event object.

Parameters:
  • dwMilliseconds (int) - Timeout in milliseconds. Use INFINITE or None for no timeout.
Returns: Event
An event that occured in one of the debugees.
Raises:
  • WindowsError - Raises an exception on error.

See Also: cont, dispatch, loop

dispatch(self, event)

 

Calls the debug event notify callbacks.

Parameters:
  • event (Event) - Event object returned by wait.
Raises:
  • WindowsError - Raises an exception on error.
Overrides: event.EventDispatcher.dispatch

See Also: cont, loop, wait

cont(self, event)

 

Resumes execution after processing a debug event.

Parameters:
  • event (Event) - Event object returned by wait.
Raises:
  • WindowsError - Raises an exception on error.

See Also: dispatch(), loop(), wait()

loop(self, dwMilliseconds=1000)

 

Main debugging loop.

Parameters:
  • dwMilliseconds (int) - Timeout for each wait, in milliseconds. Use INFINITE or None for no timeout. It's NOT recommended to use no timeout, as the user may be unable to cancel your program by pressing Control-C.
Raises:
  • WindowsError - Raises an exception on error.

See Also: cont, dispatch, wait

http://msdn.microsoft.com/en-us/library/ms681675(VS.85).aspx

get_debugee_count(self)

 
Returns: int
Number of processes being debugged.

clear(self)

 

Detach from all processes and clean up internal structures.

Raises:
  • WindowsError - Raises an exception on error.

See Also: System

notify_create_process(self, event)

 

Notify the creation of a new process.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

Warning: This method is meant to be used internally by the debugger.

notify_create_thread(self, event)

 

Notify the creation of a new thread.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

Warning: This method is meant to be used internally by the debugger.

notify_load_dll(self, event)

 

Notify the load of a new module.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

Warning: This method is meant to be used internally by the debugger.

notify_exit_process(self, event)

 

Notify the termination of a process.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.
Overrides: breakpoint.BreakpointContainer.notify_exit_process

Warning: This method is meant to be used internally by the debugger.

notify_exit_thread(self, event)

 

Notify the termination of a thread.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.
Overrides: breakpoint.BreakpointContainer.notify_exit_thread

Warning: This method is meant to be used internally by the debugger.

notify_unload_dll(self, event)

 

Notify the unload of a module.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

Warning: This method is meant to be used internally by the debugger.

notify_rip(self, event)

 

Notify of a RIP event.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

Warning: This method is meant to be used internally by the debugger.

notify_debug_control_c(self, event)

 

Notify of a Debug Ctrl-C exception.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

Warning: This method is meant to be used internally by the debugger.

Note: This exception is only raised when a debugger is attached, and applications are not supposed to handle it, so we need to handle it ourselves or the application may crash.

See Also: http://msdn.microsoft.com/en-us/library/aa363082(VS.85).aspx

notify_ms_vc_exception(self, event)

 

Notify of a Microsoft Visual C exception.

Parameters:
Returns: bool
True to call the user-defined handle, False otherwise.

Warning: This method is meant to be used internally by the debugger.

Note: This allows the debugger to understand the Microsoft Visual C thread naming convention.

See Also: http://msdn.microsoft.com/en-us/library/xcb2z8hs.aspx


Instance Variable Details [hide private]

system

A System snapshot that is automatically updated for processes being debugged. Processes not being debugged in this snapshot may be outdated.
Type:
System

   Home       Trees       Indices       Help   
Windows application debugging engine
Generated by Epydoc 3.0.1 on Tue Apr 21 15:14:38 2009 http://epydoc.sourceforge.net