| .TH WINEDBG 1 "October 2005" "@PACKAGE_STRING@" "Wine Developers Manual" |
| .SH NAME |
| winedbg \- Wine debugger |
| .SH SYNOPSIS |
| .B winedbg |
| .RI "[ " options " ] [ " program_name " [ " program_arguments " ] | " wpid " ]" |
| .PP |
| .B winedbg --gdb |
| .RI "[ " options " ] [ " program_name " [ " program_arguments " ] | " wpid " ]" |
| .PP |
| .BI "winedbg --auto " wpid |
| .PP |
| .B winedbg --minidump |
| .RI "[ " file.mdmp " ] " wpid |
| .PP |
| .BI "winedbg " file.mdmp |
| .SH DESCRIPTION |
| .B winedbg |
| is a debugger for Wine. It allows: |
| .RS 4 |
| .nf |
| + debugging native Win32 applications |
| + debugging Winelib applications |
| + being a drop-in replacement for Dr Watson |
| .fi |
| .RE |
| .PP |
| |
| .SH MODES |
| \fBwinedbg\fR can be used in five modes. The first argument to the |
| program determines the mode winedbg will run in. |
| .IP \fBdefault\fR |
| Without any explicit mode, this is standard \fBwinedbg\fR operating |
| mode. \fBwinedbg\fR will act as the front end for the user. |
| .IP \fB--gdb\fR |
| \fBwinedbg\fR will be used as a proxy for \fBgdb\fR. \fBgdb\fR will be |
| the front end for command handling, and \fBwinedbg\fR will proxy all |
| debugging requests from \fBgdb\fR to the Win32 APIs. |
| .IP \fB--auto\fR |
| This mode is used when \fBwinedbg\fR is set up in \fIAeDebug\fR |
| registry entry as the default debugger. \fBwinedbg\fR will then |
| display basic information about a crash. This is useful for users |
| who don't want to debug a crash, but rather gather relevant |
| information about the crash to be sent to developers. |
| .IP \fB--minidump\fR |
| This mode is similar to the \fB--auto\fR one, except that instead of |
| printing the information on the screen (as \fB--auto\fR does), it's |
| saved into a minidump file. The name of the file is either passed on |
| the command line, or generated by \fBWineDbg\fR when none is given. |
| This file could later on be reloaded into \fBwinedbg\fR for further |
| examination. |
| .IP \fBfile.mdmp\fR |
| In this mode \fBwinedbg\fR reloads the state of a debuggee which |
| has been saved into a minidump file. See either the \fBminidump\fR |
| command below, or the \fB--minidump mode\fR. |
| |
| .SH OPTIONS |
| When in \fBdefault\fR mode, the following options are available: |
| .PP |
| .IP \fB--command\ \fIstring\fR |
| \fBwinedbg\fR will execute the command \fIstring\fR as if it was keyed on |
| winedbg command line, and then will exit. This can be handy for |
| getting the pid of running processes (winedbg --command "info proc"). |
| .IP \fB--file\ \fIfilename\fR |
| \fBwinedbg\fR will execute the list of commands contained in file |
| filename as if they were keyed on winedbg command line, and then |
| will exit. |
| .PP |
| When in \fBgdb\fR proxy mode, the following options are available: |
| .PP |
| .IP \fB--no-start\fR |
| \fBgdb\fR will not be automatically |
| started. Relevant information for starting \fBgdb\fR is printed on |
| screen. This is somehow useful when not directly using \fBgdb\fR but |
| some graphical front-ends, like \fBddd\fR or \fBkgbd\fR. |
| .IP \fB--with-xterm\fR |
| This will run \fBgdb\fR in its own xterm instead of using the current |
| Unix console for textual display. |
| .PP |
| In all modes, the rest of the command line, when passed, is used to |
| identify which programs, if any, has to debugged: |
| .IP \fIprogram_name\fR |
| This is the name of an executable to start for a debugging |
| session. \fBwinedbg\fR will actually create a process with this |
| executable. If \fIprograms_arguments\fR are also given, they will be |
| used as arguments for creating the process to be debugged. |
| .IP \fIwpid\fR |
| \fBwinedbg\fR will attach to the process which Windows pid is \fIwpid\fR. |
| Use the \fBinfo proc\fR command within \fBwinedbg\fR to list running processes |
| and their Windows pids. |
| .IP \fBdefault\fR |
| If nothing is specified, you will enter the debugger without any run |
| nor attached process. You'll have to do the job yourself. |
| |
| .SH COMMANDS |
| .SS Default mode, and while reloading a minidump file: |
| .PP |
| Most of commands used in \fBwinedbg\fR are similar to the ones from |
| \fBgdb\fR. Please refer to the \fBgdb\fR documentations for some more |
| details. See the \fIgdb\ differences\fR section later on to get a list |
| of variations from \fBgdb\fR commands. |
| .PP |
| \fIMisc. commands\fR |
| .IP \fBabort\fR |
| Aborts the debugger. |
| .IP \fBquit\fR |
| Exits the debugger. |
| .IP \fBattach\ \fIN\fR |
| Attach to a Wine process (\fIN\fR is its Windows ID, numeric or hexadecimal). |
| IDs can be obtained using the \fBinfo\ process\fR command. Note the |
| \fBinfo\ process\fR command returns hexadecimal values |
| .IP |
| .IP \fBdetach\fR |
| Detach from a Wine-process. |
| .PP |
| \fIHelp commands\fR |
| .IP \fBhelp\fR |
| Prints some help on the commands. |
| .IP \fBhelp\ info\fR |
| Prints some help on info commands |
| .PP |
| \fIFlow control commands\fR |
| .IP \fBcont\fR |
| Continue execution until next breakpoint or exception. |
| .IP \fBpass\fR |
| Pass the exception event up to the filter chain. |
| .IP \fBstep\fR |
| Continue execution until next C line of code (enters function call) |
| .IP \fBnext\fR |
| Continue execution until next C line of code (doesn't enter function |
| call) |
| .IP \fBstepi\fR |
| Execute next assembly instruction (enters function call) |
| .IP \fBnexti\fR |
| Execute next assembly instruction (doesn't enter function call) |
| .IP \fBfinish\fR |
| Execute until return of current function is reached. |
| .PP |
| \fBcont\fR, \fBstep\fR, \fBnext\fR, \fBstepi\fR, \fBnexti\fR can be |
| postfixed by a number (N), meaning that the command must be executed N |
| times before control is returned to the user. |
| .PP |
| \fIBreakpoints, watchpoints |
| .IP \fBenable\ \fIN\fR |
| Enables (break|watch)-point \fIN\fR |
| .IP \fBdisable\ \fIN\fR |
| Disables (break|watch)-point \fIN\fR |
| .IP \fBdelete\ \fIN\fR |
| Deletes (break|watch)-point \fIN\fR |
| .IP \fBcond\ \fIN\fR |
| Removes any existing condition to (break|watch)-point \fIN\fR |
| .IP \fBcond\ \fIN\ expr\fR |
| Adds condition \fIexpr\fR to (break|watch)-point |
| \fIN\fR. \fIexpr\fR will be evaluated each time the |
| (break|watch)-point is hit. If the result is a zero value, the |
| breakpoint isn't triggered. |
| .IP \fBbreak\ *\ \fIN\fR |
| Adds a breakpoint at address \fIN\fR |
| .IP \fBbreak\ \fIid\fR |
| Adds a breakpoint at the address of symbol \fIid\fR |
| .IP \fBbreak\ \fIid\ N\fR |
| Adds a breakpoint at the line \fIN\fR inside symbol \fIid\fR. |
| .IP \fBbreak\ \fIN\fR |
| Adds a breakpoint at line \fIN\fR of current source file. |
| .IP \fBbreak\fR |
| Adds a breakpoint at current \fB$PC\fR address. |
| .IP \fBwatch\ *\ \fIN\fR |
| Adds a watch command (on write) at address \fIN\fR (on 4 bytes). |
| .IP \fBwatch\ \fIid\fR |
| Adds a watch command (on write) at the address of symbol |
| \fIid\fR. Size depends on size of \fIid\fR. |
| .IP \fBrwatch\ *\ \fIN\fR |
| Adds a watch command (on read) at address \fIN\fR (on 4 bytes). |
| .IP \fBrwatch\ \fIid\fR |
| Adds a watch command (on read) at the address of symbol |
| \fIid\fR. Size depends on size of \fIid\fR. |
| .IP \fBinfo\ break\fR |
| Lists all (break|watch)-points (with their state). |
| .PP |
| You can use the symbol \fBEntryPoint\fR to stand for the entry point of the Dll. |
| .PP |
| When setting a (break|watch)-point by \fIid\fR, if the symbol cannot |
| be found (for example, the symbol is contained in a not yet loaded |
| module), \fBwinedbg\fR will recall the name of the symbol and will try |
| to set the breakpoint each time a new module is loaded (until it succeeds). |
| .PP |
| \fIStack manipulation\fR |
| .IP \fBbt\fR |
| Print calling stack of current thread. |
| .IP \fBbt\ \fIN\fR |
| Print calling stack of thread of ID \fIN\fR. Note: this doesn't change |
| the position of the current frame as manipulated by the \fBup\fR & |
| \fBdn\fR commands). |
| .IP \fBup\fR |
| Goes up one frame in current thread's stack |
| .IP \fBup\ \fIN\fR |
| Goes up \fIN\fR frames in current thread's stack |
| .IP \fBdn\fR |
| Goes down one frame in current thread's stack |
| .IP \fBdn\ \fIN\fR |
| Goes down \fIN\fR frames in current thread's stack |
| .IP \fBframe\ \fIN\fR |
| Sets \fIN\fR as the current frame for current thread's stack. |
| .IP \fBinfo\ locals\fR |
| Prints information on local variables for current function frame. |
| .PP |
| \fIDirectory & source file manipulation\fR |
| .IP \fBshow\ dir\fR |
| Prints the list of dirs where source files are looked for. |
| .IP \fBdir\ \fIpathname\fR |
| Adds \fIpathname\fR to the list of dirs where to look for source |
| files |
| .IP \fBdir\fR |
| Deletes the list of dirs where to look for source files |
| .IP \fBsymbolfile\ \fIpathname\fR |
| Loads external symbol definition file \fIpathname\fR |
| .IP \fBsymbolfile\ \fIpathname\ N\fR |
| Loads external symbol definition file \fIpathname\fR (applying |
| an offset of \fIN\fR to addresses) |
| .IP \fBlist\fR |
| Lists 10 source lines forwards from current position. |
| .IP \fBlist\ -\fR |
| Lists 10 source lines backwards from current position |
| .IP \fBlist\ \fIN\fR |
| Lists 10 source lines from line \fIN\fR in current file |
| .IP \fBlist\ \fIpathname\fB:\fIN\fR |
| Lists 10 source lines from line \fIN\fR in file \fIpathname\fR |
| .IP \fBlist\ \fIid\fR |
| Lists 10 source lines of function \fIid\fR |
| .IP \fBlist\ *\ \fIN\fR |
| Lists 10 source lines from address \fIN\fR |
| .PP |
| You can specify the end target (to change the 10 lines value) using |
| the ',' separator. For example: |
| .IP \fBlist\ 123,\ 234\fR |
| lists source lines from line 123 up to line 234 in current file |
| .IP \fBlist\ foo.c:1,56\fR |
| lists source lines from line 1 up to 56 in file foo.c |
| .PP |
| \fIDisplaying\fR |
| .PP |
| A display is an expression that's evaluated and printed after the |
| execution of any \fBwinedbg\fR command. |
| .IP \fBdisplay\fR |
| .IP \fBinfo\ display\fR |
| Lists the active displays |
| .IP \fBdisplay\ \fIexpr\fR |
| Adds a display for expression \fIexpr\fR |
| .IP \fBdisplay\ /\fIfmt\ \fIexpr\fR |
| Adds a display for expression \fIexpr\fR. Printing evaluated |
| \fIexpr\fR is done using the given format (see \fBprint\ command\fR |
| for more on formats) |
| .IP \fBdel\ display\ \fIN\fR |
| .IP \fBundisplay\ \fIN\fR |
| Deletes display \fIN\fR |
| .PP |
| \fIDisassembly\fR |
| .IP \fBdisas\fR |
| Disassemble from current position |
| .IP \fBdisas\ \fIexpr\fR |
| Disassemble from address \fIexpr\fR |
| .IP \fBdisas\ \fIexpr\fB,\fIexpr\fR |
| Disassembles code between addresses specified by the two expressions |
| .PP |
| \fIMemory\ (reading,\ writing,\ typing)\fR |
| .IP \fBx\ \fIexpr\fR |
| Examines memory at address \fIexpr\fR |
| .IP \fBx\ /\fIfmt\ expr\fR |
| Examines memory at address \fIexpr\fR using format \fIfmt\fR |
| .IP \fBprint\ \fIexpr\fR |
| Prints the value of \fIexpr\fR (possibly using its type) |
| .IP \fBprint\ /\fIfmt\ expr\fR |
| Prints the value of \fIexpr\fR (possibly using its type) |
| .IP \fBset\ \fIvar\fB\ =\ \fIexpr\fR |
| Writes the value of \fIexpr\fR in \fIvar\fR variable |
| .IP \fBwhatis\ \fIexpr\fR |
| Prints the C type of expression \fIexpr\fR |
| .PP |
| .IP \fIfmt\fR |
| is either \fIletter\fR or \fIcount letter\fR, where \fIletter\fR |
| can be: |
| .RS 4 |
| .IP s |
| an ASCII string |
| .IP u |
| a UTF16 Unicode string |
| .IP i |
| instructions (disassemble) |
| .IP x |
| 32-bit unsigned hexadecimal integer |
| .IP d |
| 32-bit signed decimal integer |
| .IP w |
| 16-bit unsigned hexadecimal integer |
| .IP c |
| character (only printable 0x20-0x7f are actually printed) |
| .IP b |
| 8-bit unsigned hexadecimal integer |
| .IP g |
| Win32 GUID |
| .RE |
| .PP |
| \fIExpressions\fR |
| .PP |
| Expressions in Wine Debugger are mostly written in a C form. However, |
| there are a few discrepancies: |
| .PP |
| .RS 4 |
| Identifiers can take a '!' in their names. This allows mainly to |
| specify a module where to look the ID from, e.g. \fIUSER32!CreateWindowExA\fR. |
| .PP |
| In a cast operation, when specifying a structure or a union, you must |
| use the struct or union keyword (even if your program uses a typedef). |
| .RE |
| .PP |
| When specifying an identifier, if several symbols with |
| this name exist, the debugger will prompt for the symbol you want to |
| use. Pick up the one you want from its number. |
| .PP |
| \fIMisc.\fR |
| .PP |
| .BI "minidump " file.mdmp |
| saves the debugging context of the debuggee into a minidump file called |
| \fIfile.mdmp\fR. |
| .PP |
| \fIInformation on Wine internals\fR |
| .IP \fBinfo\ class\fR |
| Lists all Windows classes registered in Wine |
| .IP \fBinfo\ class\ \fIid\fR |
| Prints information on Windows class \fIid\fR |
| .IP \fBinfo\ share\fR |
| Lists all the dynamic libraries loaded in the debugged program |
| (including .so files, NE and PE DLLs) |
| .IP \fBinfo\ share\ \fIN\fR |
| Prints information on module at address \fIN\fR |
| .IP \fBinfo\ regs\fR |
| Prints the value of the CPU registers |
| .IP \fBinfo\ all-regs\fR |
| Prints the value of the CPU and Floating Point registers |
| .IP \fBinfo\ segment\fR |
| Lists all allocated segments (i386 only) |
| .IP \fBinfo\ segment\ \fIN\fR |
| Prints information on segment \fIN\fR (i386 only) |
| .IP \fBinfo\ stack\fR |
| Prints the values on top of the stack |
| .IP \fBinfo\ map\fR |
| Lists all virtual mappings used by the debugged program |
| .IP \fBinfo\ map\ \fIN\fR |
| Lists all virtual mappings used by the program of Windows pid \fIN\fR |
| .IP \fBinfo\ wnd\fR |
| Displays the window hierarchy starting from the desktop window |
| .IP \fBinfo\ wnd\ \fIN\fR |
| Prints information of Window of handle \fIN\fR |
| .IP \fBinfo\ process\fR |
| Lists all w-processes in Wine session |
| .IP \fBinfo\ thread\fR |
| Lists all w-threads in Wine session |
| .IP \fBinfo\ frame\fR |
| Lists the exception frames (starting from current stack frame). You |
| can also pass, as optional argument, a thread id (instead of current |
| thread) to examine its exception frames. |
| .PP |
| Debug messages can be turned on and off as you are debugging using |
| the \fBset\fR command, but only for channels initialized with the |
| \fIWINEDEBUG\fR environment variable. |
| .IP \fBset\ warn\ +\ \fIwin\fR |
| Turns on warn on \fIwin\fR channel |
| .IP \fBset\ +\ \fIwin\fR |
| Turns on warn/fixme/err/trace on \fIwin\fR channel |
| .IP \fBset\ -\ \fIwin\fR |
| Turns off warn/fixme/err/trace on \fIwin\fR channel |
| .IP \fBset\ fixme\ -\ all\fR |
| Turns off fixme class on all channels |
| .PP |
| .SS Gdb mode: |
| .PP |
| See the \fBgdb\fR documentation for all the \fBgdb\fR commands. |
| .PP |
| However, a few Wine extensions are available, through the |
| \fBmonitor\fR command: |
| .IP \fBmonitor\ wnd\fR |
| Lists all windows in the Wine session |
| .IP \fBmonitor\ proc\fR |
| Lists all processes in the Wine session |
| .IP \fBmonitor\ mem\fR |
| Displays memory mapping of debugged process |
| .PP |
| .SS Auto and minidump modes: |
| .PP |
| Since no user input is possible, no commands are available. |
| |
| .SH ENVIRONMENT |
| .IP \fBWINE_GDB\fR |
| When used in \fBgdb\fR proxy mode, \fBWINE_GDB\fR specifies the name |
| (and the path) of the executable to be used for \fBgdb\fR. "gdb" |
| is used by default. |
| .SH AUTHORS |
| The first version was written by Eric Youngdale. |
| .PP |
| See Wine developers list for the rest of contributors. |
| .SH BUGS |
| Bugs can be reported on the |
| .UR http://bugs.winehq.org |
| .B Wine bug tracker |
| .UE . |
| .SH AVAILABILITY |
| .B winedbg |
| is part of the Wine distribution, which is available through WineHQ, |
| the |
| .UR http://www.winehq.org/ |
| .B Wine development headquarters |
| .UE . |
| .SH "SEE ALSO" |
| .BR wine (1), |
| .br |
| .UR http://www.winehq.org/help |
| .B Wine documentation and support |
| .UE . |