423 lines
14 KiB
Groff
423 lines
14 KiB
Groff
.TH WINEDBG 1 "October 2005" "Wine 4.6" "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--port\fR\ \fIport\fR
|
|
Start the \fBgdb\fR server on the given port. If this option is not
|
|
specified, a randomly chosen port will be used. If \fB--no-start\fR is
|
|
specified, the port used will be printed on startup.
|
|
.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 https://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 https://www.winehq.org/
|
|
.B Wine development headquarters
|
|
.UE .
|
|
.SH "SEE ALSO"
|
|
.BR wine (1),
|
|
.br
|
|
.UR https://www.winehq.org/help
|
|
.B Wine documentation and support
|
|
.UE .
|