WineHQ
WineHQ

1.2. WineDbg modes of invocation

1.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

1.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) using the info process command, and then, with the attach command, pick up the wpid of the W-process you want to debug. This is a neat feature as it allows you to debug an already started application.

1.2.3. On exceptions

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

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 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.

1.2.4. Interrupting

You can stop the debugger while it's running by hitting Ctrl-C in its window. This will stop the debugged process, and let you manipulate the current context.

1.2.5. Quitting

Wine supports the new XP APIs, allowing for a debugger to detach from a program being debugged (see detach command).