git.oblomov.eu Git - wine/blob - programs/winedbg/winedbg.man.in

   1 .\" -*- nroff -*-
   2 .TH WINEDBG 1 "October 2005" "@PACKAGE_STRING@" "Wine Developers Manual"
   3 .SH NAME
   4 winedbg \- Wine's debugger
   5 .SH SYNOPSIS
   6 .BR "winedbg "
   7 .RI "[" " options " "] ["
   8 .BI "program name"
   9 .RI "[ program arguments ] |"
  10 .BI "pid"
  11 .RI "]"
  12 .PP
  13 .BR "winedbg "
  14 .BI "--gdb"
  15 .RI "[" " options " "] ["
  16 .BI "program name"
  17 .RI "[ program arguments ] |"
  18 .BI "pid"
  19 .RI "]"
  20 .PP
  21 .BR "winedbg "
  22 .BI "--auto "
  23 .BI "pid"
  24 .PP
  25 .BR "winedbg "
  26 .BI "--minidump "
  27 .RI "[ file.mdmp ]"
  28 .BI "pid"
  29 .PP
  30 .BR "winedbg"
  31 .BI "file.mdmp"
  32 .SH DESCRIPTION
  33 .B winedbg
  34 is a debugger for Wine. It allows:
  35 .RS 4
  36 + debugging native Win32 applications
  37 .nf
  38 + debugging Winelib applications.
  39 .nf
  40 + being a drop-in replacement for Dr Watson
  41 .RE
  42 .PP
  43
  44 .SH MODES
  45 \fBwinedbg\fR can be used in five modes.  The first argument to the
  46 program determines the mode winedbg will run in.
  47 .IP \fBdefault\fR
  48 Without any explicit mode, this is standard \fBwinedbg\fR operating
  49 mode. \fBwinedbg\fR will act as the front end for the user.
  50 .IP \fB--gdb\fR
  51 \fBwinedbg\fR will be used as a proxy for \fBgdb\fR. \fBgdb\fR will be
  52 the front end for command handling, and \fBwinedbg\fR will proxy all
  53 debugging requests from \fBgdb\fR to the Win32 APIs.
  54 .IP \fB--auto\fR
  55 This mode is used when \fBwinedbg\fR is set up in \fIAeDebug\fR
  56 registry entry as the default debugger. \fBwinedbg\fR will then
  57 display basic information about a crash. This is useful for users
  58 who don't want to debug a crash, but rather gather relevant
  59 information about the crash to be sent to developers.
  60 .IP \fB--minidump\fR
  61 This mode is similar to the \fB--auto\fR one, except that instead of
  62 printing the information on the screen (as \fB--auto\fR does), it's
  63 saved into a minidump file. The name of the file is either passed on
  64 the command line, or generated by \fBWineDbg\fR when none is given.
  65 This file could later on be reloaded into \fBwinedbg\fR for further
  66 examination.
  67 .IP \fBfile.mdmp\fR
  68 This mode allows to reload into \fBwinedbg\fR the state of a debuggee
  69 which has been saved into a minidump file. See either the \fBminidump\fR
  70 command below, or the \fB--minidump mode\fR.
  71
  72 .SH OPTIONS
  73 When in \fBdefault\fR mode, the following options are available:
  74 .PP
  75 .IP \fI--command\ <string>\fR
  76 \fBwinedbg\fR will execute the command <string> as if it was keyed on
  77 winedbg's command line, and then will exit. This can be handy for
  78 getting the pid of running processes (winedbg --command "info proc").
  79 .IP \fI--file\ <filename>\fR
  80 \fBwinedbg\fR will execute the list of commands contained in file
  81 <filename> as if they were keyed on winedbg's command line, and then
  82 will exit.
  83 .PP
  84
  85 When in \fBgdb\fR proxy mode, the following options are available:
  86 .PP
  87 .IP \fI--no-start\fR
  88 \fBgdb\fR will not be automatically
  89 started. Relevant information for starting \fBgdb\fR are printed on
  90 screen. This is somehow useful when not directly using \fBgdb\fR but
  91 some graphical front-ends, like \fBddd\fR or \fBkgbd\fR.
  92 .IP \fI--with-xterm\fR
  93 This will run \fBgdb\fR in its own xterm instead of using the current
  94 Unix console for textual display.
  95 .PP
  96 In all modes, the rest of the command line, when passed, is used to
  97 identify which programs, if any, has to debugged:
  98 .IP \fBprogram\ name\fR
  99 This is the name of an executable to start for a debugging
 100 session.  \fBwinedbg\fR will actually create a process with this
 101 executable. If \fBprograms arguments\fR are also given, they will be
 102 used as arguments for creating the process to be debugged.
 103 .IP \fBpid\fR
 104 \fBwinedbg\fR will attach to the process which pid is \fBpid\fR (pids
 105 refer to Win32 pids, not Unix pids). Use the \fIinfo proc\fR
 106 \fBwinedbg\fR command to list running processes and their Win32 pids.
 107 .IP \fBdefault\fR
 108 If nothing is specified, you will enter the debugger without any run
 109 nor attached process. You'll have to do the job yourself.
 110
 111 .SH COMMANDS
 112 .SS Default mode, and while reloading a minidump file:
 113 .PP
 114 Most of commands used in \fBwinedbg\fR are similar to the ones from
 115 \fBgdb\fR. Please refer to the \fBgdb\fR documentations for some more
 116 details. See the \fIgdb\ differences\fR section later on to get a list
 117 of variations from \fBgdb\fR commands.
 118 .PP
 119 \fIMisc. commands\fR
 120 .IP \fBabort\fR
 121 Aborts the debugger.
 122 .IP \fBquit\fR
 123 Exits the debugger.
 124 .IP \fBattach\ N\fR
 125 Attach to a Wine-process (\fBN\fR is its ID, numeric or hexadecimal).
 126 IDs can be obtained using the \fBinfo\ process\fR command.  Note the
 127 \fBinfo\ process\fR command returns hexadecimal values
 128 .IP
 129 .IP \fBdetach\fR
 130 Detach from a Wine-process.
 131 .PP
 132 \fIHelp commands\fR
 133 .IP \fBhelp\fR
 134 Prints some help on the commands.
 135 .IP \fBhelp\ info\fR
 136 Prints some help on info commands
 137 .PP
 138 \fIFlow control commands\fR
 139 .IP \fBcont\fR
 140 Continue execution until next breakpoint or exception.
 141 .IP \fBpass\fR
 142 Pass the exception event up to the filter chain.
 143 .IP \fBstep\fR
 144 Continue execution until next C line of code (enters function call)
 145 .IP \fBnext\fR
 146 Continue execution until next C line of code (doesn't enter function
 147 call)
 148 .IP \fBstepi\fR
 149 Execute next assembly instruction (enters function call)
 150 .IP \fBnexti\fR
 151 Execute next assembly instruction (doesn't enter function call)
 152 .IP \fBfinish\fR
 153 Execute until return of current function is reached.
 154 .PP
 155 \fBcont\fR, \fBstep\fR, \fBnext\fR, \fBstepi\fR, \fBnexti\fR can be
 156 postfixed by a number (N), meaning that the command must be executed N
 157 times before control is returned to the user.
 158 .PP
 159 \fIBreakpoints, watchpoints
 160 .IP \fBenable\ N\fR
 161 Enables (break|watch)-point #\fBN\fR
 162 .IP \fBdisable\fR
 163 Disables (break|watch)-point \fB#N\fR
 164 .IP \fBdelete\fR
 165 Deletes (break|watch)-point #\fBN\fR
 166 .IP \fBcond\ N\fR
 167 Removes any existing condition to (break|watch)-point \fBN\fR
 168 .IP \fBcond\ N\ <expr>\fR
 169 Adds condition \fB<expr>\fR to (break|watch)-point
 170 #\fBN\fR. \fB<expr>\fR will be evaluated each time the
 171 (break|watch)-point is hit. If the result is a zero value, the
 172 breakpoint isn't triggered.
 173 .IP \fBbreak\ *\ N\fR
 174 Adds a breakpoint at address \fBN\fR
 175 .IP \fBbreak\ <id>\fR
 176 Adds a breakpoint at the address of symbol \fB<id>\fR
 177 .IP \fBbreak\ <id>\ N\fR
 178 Adds a breakpoint at the line \fBN\fR inside symbol \fB<id>\fR.
 179 .IP \fBbreak\ N\fR
 180 Adds a breakpoint at line \fBN\fR of current source file.
 181 .IP \fBbreak\fR
 182 Adds a breakpoint at current \f$PC\fR address.
 183 .IP \fBwatch\ *\ N\fR
 184 Adds a watch command (on write) at address \fBN\fR (on 4 bytes).
 185 .IP \fBwatch\ <id>\fR
 186 Adds a watch command (on write) at the address of symbol
 187 \fB<id>\fR. Size depends on size of \fB<id>\fR.
 188 .IP \fBinfo\ break\fR
 189 Lists all (break|watch)-points (with their state).
 190 .PP
 191 You can use the symbol \fBEntryPoint\fR to stand for the entry point of the Dll.
 192 .PP
 193 When setting a (break|watch)-point by \fB<id>\fR, if the symbol cannot
 194 be found (for example, the symbol is contained in a not yet loaded
 195 module), \fBwinedbg\fR will recall the name of the symbol and will try
 196 to set the breakpoint each time a new module is loaded (until it succeeds).
 197 .PP
 198 \fIStack manipulation\fR
 199 .IP \fBbt\fR
 200 Print calling stack of current thread.
 201 .IP \fBbt\ N\fR
 202 Print calling stack of thread of ID \fBN\fR. Note: this doesn't change
 203 the position of the current frame as manipulated by the \fBup\fR &
 204 \fBdn\fR commands).
 205 .IP \fBup\fR
 206 Goes up one frame in current thread's stack
 207 .IP \fBup\ N\fR
 208 Goes up \fBN\fR frames in current thread's stack
 209 .IP \fBdn\fR
 210 Goes down one frame in current thread's stack
 211 .IP \fBdn\ N\fR
 212 Goes down \fBN\fR frames in current thread's stack
 213 .IP \fBframe\ N\fR
 214 Sets \fBN\fR as the current frame for current thread's stack.
 215 .IP \fBinfo\ locals\fR
 216 Prints information on local variables for current function frame.
 217 .PP
 218 \fIDirectory & source file manipulation\fR
 219 .IP \fBshow\ dir\fR
 220 Prints the list of dir:s where source files are looked for.
 221 .IP \fBdir\ <pathname>\fR
 222 Adds \fB<pathname>\fR to the list of dir:s where to look for source
 223 files
 224 .IP \fBdir\fR
 225 Deletes the list of dir:s where to look for source files
 226 .IP \fBsymbolfile\ <pathname>\fR
 227 Loads external symbol definition symbolfile \fB<pathname>\fR
 228 .IP \fBsymbolfile\ <pathname>\ N\fR
 229 Loads external symbol definition symbolfile \fB<pathname>\fR (applying
 230 an offset of \fBN\fR to addresses)
 231 .IP \fBlist\fR
 232 Lists 10 source lines forwards from current position.
 233 .IP \fBlist\ -\fR
 234 Lists 10 source lines backwards from current position
 235 .IP \fBlist\ N\fR
 236 Lists 10 source lines from line #\fBN\fR in current file
 237 .IP \fBlist\ <pathname>:N\fR
 238 Lists 10 source lines from line #\fBN\fR in file \fB<pathname>\fR
 239 .IP \fBlist\ <id>\fR
 240 Lists 10 source lines of function \fB<id>\fR
 241 .IP \fBlist\ *\ N\fR
 242 Lists 10 source lines from address \fBN\fR
 243 .PP
 244 You can specify the end target (to change the 10 lines value) using
 245 the ',' separator. For example:
 246 .nf
 247 .IP \fBlist\ 123,\ 234\fR
 248 lists source lines from line 123 up to line 234 in current file
 249 .nf
 250 .IP \fBlist\ foo.c:1,56\fR
 251 lists source lines from line 1 up to 56 in file foo.c
 252 .PP
 253 \fIDisplaying\fR
 254 .PP
 255 A display is an expression that's evaluated and printed after the
 256 execution of any \fBwinedbg\fR's command.
 257 .IP \fBdisplay\fR
 258 .IP \fBinfo\ display\fR
 259 Lists the active displays
 260 .IP \fBdisplay\ <expr>\fR
 261 Adds a display for expression \f<expr>\fR
 262 .IP \fBdisplay\ /fmt\ <expr>\fR
 263 Adds a display for expression \fB<expr>\fR. Printing evaluated
 264 \fB<expr>\fR is done using the given format (see \fBprint\ command\fR
 265 for more on formats)
 266 .IP \fBdel\ display\ N\fR
 267 .IP \fBundisplay\ N\fR
 268 Deletes display #\fBN\fR
 269 .PP
 270 \fIDisassembly\fR
 271 .IP \fBdisas\fR
 272 Disassemble from current position
 273 .IP \fBdisas\ <expr>\fR
 274 Disassemble from address \fB<expr>\fR
 275 .IP \fBdisas\ <expr>,<expr>\fR
 276 Disassembles code between addresses specified by the two \fB<expr>\fR:s
 277 .PP
 278 \fIMemory\ (reading,\ writing,\ typing)\fR
 279 .IP \fBx\ <expr>\fR
 280 Examines memory at \fB<expr>\fR address
 281 .IP \fBx\ /fmt\ <expr>\fR
 282 Examines memory at \fB<expr>\fR address using format \fI/fmt\fR
 283 .IP \fBprint\ <expr>\fR
 284 Prints the value of \fB<expr>\fR (possibly using its type)
 285 .IP \fBprint\ /fmt\ <expr>\fR
 286 Prints the value of \fB<expr>\fR (possibly using its type)
 287 .IP \fBset\ <var>\ =\ <expr>\fR
 288 Writes the value of \fB<expr>\fR in \fB<var>\fR variable.
 289 .IP \fBwhatis\ <expr>\fR
 290 Prints the C type of expression \fB<expr>\fR
 291 .PP
 292 .IP \fI/fmt\fR
 293 is either \fI/<letter>\fR or \fI/<count><letter>\fR. \fI<letter>\fR
 294 can be:
 295 .RS 4
 296 .IP s
 297 an ASCII string
 298 .IP u
 299 an Unicode UTF16 string
 300 .IP i
 301 instructions (disassemble)
 302 .IP x
 303 32 bit unsigned hexadecimal integer
 304 .IP d
 305 32 bit signed decimal integer
 306 .IP w
 307 16 bit unsigned hexadecimal integer
 308 .IP c
 309 character (only printable 0x20-0x7f are actually printed)
 310 .IP b
 311 8 bit unsigned hexadecimal integer
 312 .IP g
 313 Win32 GUID
 314 .RE
 315 .PP
 316 \fIExpressions\fR
 317 .PP
 318 Expressions in Wine Debugger are mostly written in a C form. However,
 319 there are a few discrepancies:
 320 .PP
 321 .RS 4
 322 Identifiers can take a '!' in their names. This allows mainly to
 323 specify a module where to look the module from: \fIUSER32!CreateWindowExA\fR.
 324 .PP
 325 In cast operation, when specifying a structure or an union, you must
 326 use the struct or union key word (even if your program uses a typedef).
 327 .RE
 328 .PP
 329 When specifying an identifier \fB<id>\fR, if several symbols with
 330 this name exist, the debugger will prompt for the symbol you want to
 331 use. Pick up the one you want from its number.
 332 .PP
 333 \fIMisc.\fR
 334 .PP
 335 .IP \fBminidump\ file.mdmp\fR
 336 saves the debugging context of the debuggee into a minidump file called
 337 file.mdmp
 338 .PP
 339 \fIInformation on Wine's internals\fR
 340 .IP \fBinfo\ class\fR
 341 Lists all Windows' class registered in Wine
 342 .IP \fBinfo\ class\ <id>\fR
 343 Prints information on Windows's class \fB<id>\fR
 344 .IP \fBinfo\ share\fR
 345 Lists all the dynamic libraries loaded in the debugged program
 346 (including .so files, NE and PE DLLs)
 347 .IP \fBinfo\ share\ N\fR
 348 Prints information on module at address \fBN\fR
 349 .IP \fBinfo\ regs\fR
 350 Prints the value of the CPU registers
 351 .IP \fBinfo\ all-regs\fR
 352 Prints the value of the CPU and Floating Point registers
 353 .IP \fBinfo\ segment\fR
 354 Lists all allocated segments (i386 only)
 355 .IP \fBinfo\ segment\ N\fR
 356 Prints information on segment \fBN\fR (i386 only)
 357 .IP \fBinfo\ stack\fR
 358 Prints the values on top of the stack
 359 .IP \fBinfo\ map\fR
 360 Lists all virtual mappings used by the debugged program
 361 .IP \fBinfo\ map\ N\fR
 362 Lists all virtual mappings used by the program of pid \fBN\fR
 363 .IP \fBinfo\ wnd\fR
 364 Displays the window hierarchy starting from the desktop window
 365 .IP \fBinfo\ wnd\ N\fR
 366 Prints information of Window of handle \fBN\fR
 367 .IP \fBinfo\ process\fR
 368 Lists all w-processes in Wine session
 369 .IP \fBinfo\ thread\fR
 370 Lists all w-threads in Wine session
 371 .IP \fBinfo\ exception\fR
 372 Lists the exception frames (starting from current stack frame)
 373 .PP
 374 It is possible to turn on and off Wine's debug messages as you are
 375 debugging using the \fBset\fR command.
 376 .IP \fBset\ +\ warn\ win\fR
 377 Turns on warn on \fB'win'\fR channel
 378 .IP \fBset\ +\ win\fR
 379 Turns on warn/fixme/err/trace on \fB'win'\fR channel
 380 .IP \fBset\ -\ win\fR
 381 Turns off warn/fixme/err/trace on \fB'win'\fR channel
 382 .IP \fBset\ -\ fixme\fR
 383 Turns off the 'fixme' class on all channels
 384 .PP
 385 .SS Gdb mode:
 386 .PP
 387 See the \fBgdb\fR documentation for all the \fBgdb\fR commands.
 388 .PP
 389 However, a few Wine's extension are available, through the
 390 \fBmonitor\fR command:
 391 .IP \fBmonitor\ wnd\fR
 392 Lists all window in the Wine session
 393 .IP \fBmonitor\ proc\fR
 394 Lists all processes in the Wine session
 395 .IP \fBmonitor\ mem\fR
 396 Displays memory mapping of debugged process
 397 .PP
 398 .SS Auto and minidump modes:
 399 .PP
 400 Since no user input is possible, no commands are available.
 401
 402 .SH ENVIRONMENT
 403 .IP \fBWINE_GDB\fR
 404 When used in \fBgdb\fR proxy mode, \fBWINE_GDB\fR specifies the name
 405 (and the path) of the executable to be used for \fBgdb\fR. \fB"gdb"\fR
 406 is used by default.
 407 .SH FILES
 408 No specific files are used (yet).
 409 .SH BUGS
 410 A lot.
 411 .SH AUTHORS
 412 The first version was written by Eric Youngdale.
 413 .PP
 414 See Wine developer's list for the rest of contributors.
 415 .SH "SEE ALSO"
 416 .BR winedbg "'s README file"
 417 .nf
 418 The Winelib User Guide
 419 .nf
 420 The Wine Developers Guide