                              Wine Documentation                               
Prev                       Chapter 2. Debugging Wine                       Next
-------------------------------------------------------------------------------

2.2. WineDbg's modes of invocation

2.2.1. Starting a process

Any application (either a Windows' native executable, or a Winelib application)
can be run through WineDbg. Command line options and tricks are the same as for
wine:

winedbg telnet.exe
winedbg "hl.exe -windowed"
        

2.2.2. Attaching

WineDbg can also be launched without any command line argument: WineDbg is
started without any attached process. You can get a list of running W-processes
(and their wpid's) using the walk process command, and then, with the attach
command, pick up the wpid of the W-process you want to debug. This is (for now)
a neat feature for the following reasons:

  * you can debug an already started application
   
2.2.3. On exception

When something goes wrong, Windows tracks this as an exception. Exceptions
exist for segmentation violation, stack overflow, division by zero...

When an exception occurs, Wine checks if the W-process is debugged. If so, the
exception event is sent to the debugger, which takes care of it: end of the
story. This mechanism is part of the standard Windows' debugging API.

If the W-process is not debugged, Wine tries to launch a debugger. This
debugger (normally WineDbg, see III Configuration for more details), at
startup, attaches to the W-process which generated the exception event. In this
case, you are able to look at the causes of the exception, and either fix the
causes (and continue further the execution) or dig deeper to understand what
went wrong.

If WineDbg is the standard debugger, the pass and cont commands are the two
ways to let the process go further for the handling of the exception event.

To be more precise on the way Wine (and Windows) generates exception events,
when a fault occurs (segmentation violation, stack overflow...), the event is
first sent to the debugger (this is known as a first chance exception). The
debugger can give two answers:

continue:
   
    the debugger had the ability to correct what's generated the exception, and
    is now able to continue process execution.
   
pass:
   
    the debugger couldn't correct the cause of the first chance exception. Wine
    will now try to walk the list of exception handlers to see if one of them
    can handle the exception. If no exception handler is found, the exception
    is sent once again to the debugger to indicate the failure of the exception
    handling.
   
Note since some of Wine's code uses exceptions and try/catch blocks to provide 
     some functionality, WineDbg can be entered in such cases with segv        
     exceptions. This happens, for example, with IsBadReadPtr function. In that
     case, the pass command shall be used, to let the handling of the exception
     to be done by the catch block in IsBadReadPtr.                            

2.2.4. Quitting

Unfortunately, Windows doesn't provide a detach kind of API, meaning that once
you started debugging a process, you must do so until the process dies. Killing
(or stopping/aborting) the debugger will also kill the debugged process. This
will be true for any Windows' debugging API compliant debugger, starting with 
WineDbg.

-------------------------------------------------------------------------------
Prev                                 Home                                  Next
Debugging Wine                        Up                Using the Wine Debugger
