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 .nf
  37 + debugging native Win32 applications
  38 + debugging Winelib applications.
  39 + being a drop-in replacement for Dr Watson
  40 .fi
  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 .IP \fBlist\ 123,\ 234\fR
 247 lists source lines from line 123 up to line 234 in current file
 248 .IP \fBlist\ foo.c:1,56\fR
 249 lists source lines from line 1 up to 56 in file foo.c
 250 .PP
 251 \fIDisplaying\fR
 252 .PP
 253 A display is an expression that's evaluated and printed after the
 254 execution of any \fBwinedbg\fR's command.
 255 .IP \fBdisplay\fR
 256 .IP \fBinfo\ display\fR
 257 Lists the active displays
 258 .IP \fBdisplay\ <expr>\fR
 259 Adds a display for expression \f<expr>\fR
 260 .IP \fBdisplay\ /fmt\ <expr>\fR
 261 Adds a display for expression \fB<expr>\fR. Printing evaluated
 262 \fB<expr>\fR is done using the given format (see \fBprint\ command\fR
 263 for more on formats)
 264 .IP \fBdel\ display\ N\fR
 265 .IP \fBundisplay\ N\fR
 266 Deletes display #\fBN\fR
 267 .PP
 268 \fIDisassembly\fR
 269 .IP \fBdisas\fR
 270 Disassemble from current position
 271 .IP \fBdisas\ <expr>\fR
 272 Disassemble from address \fB<expr>\fR
 273 .IP \fBdisas\ <expr>,<expr>\fR
 274 Disassembles code between addresses specified by the two \fB<expr>\fR:s
 275 .PP
 276 \fIMemory\ (reading,\ writing,\ typing)\fR
 277 .IP \fBx\ <expr>\fR
 278 Examines memory at \fB<expr>\fR address
 279 .IP \fBx\ /fmt\ <expr>\fR
 280 Examines memory at \fB<expr>\fR address using format \fI/fmt\fR
 281 .IP \fBprint\ <expr>\fR
 282 Prints the value of \fB<expr>\fR (possibly using its type)
 283 .IP \fBprint\ /fmt\ <expr>\fR
 284 Prints the value of \fB<expr>\fR (possibly using its type)
 285 .IP \fBset\ <var>\ =\ <expr>\fR
 286 Writes the value of \fB<expr>\fR in \fB<var>\fR variable.
 287 .IP \fBwhatis\ <expr>\fR
 288 Prints the C type of expression \fB<expr>\fR
 289 .PP
 290 .IP \fI/fmt\fR
 291 is either \fI/<letter>\fR or \fI/<count><letter>\fR. \fI<letter>\fR
 292 can be:
 293 .RS 4
 294 .IP s
 295 an ASCII string
 296 .IP u
 297 a UTF16 Unicode string
 298 .IP i
 299 instructions (disassemble)
 300 .IP x
 301 32 bit unsigned hexadecimal integer
 302 .IP d
 303 32 bit signed decimal integer
 304 .IP w
 305 16 bit unsigned hexadecimal integer
 306 .IP c
 307 character (only printable 0x20-0x7f are actually printed)
 308 .IP b
 309 8 bit unsigned hexadecimal integer
 310 .IP g
 311 Win32 GUID
 312 .RE
 313 .PP
 314 \fIExpressions\fR
 315 .PP
 316 Expressions in Wine Debugger are mostly written in a C form. However,
 317 there are a few discrepancies:
 318 .PP
 319 .RS 4
 320 Identifiers can take a '!' in their names. This allows mainly to
 321 specify a module where to look the module from: \fIUSER32!CreateWindowExA\fR.
 322 .PP
 323 In cast operation, when specifying a structure or an union, you must
 324 use the struct or union key word (even if your program uses a typedef).
 325 .RE
 326 .PP
 327 When specifying an identifier \fB<id>\fR, if several symbols with
 328 this name exist, the debugger will prompt for the symbol you want to
 329 use. Pick up the one you want from its number.
 330 .PP
 331 \fIMisc.\fR
 332 .PP
 333 .IP \fBminidump\ file.mdmp\fR
 334 saves the debugging context of the debuggee into a minidump file called
 335 file.mdmp
 336 .PP
 337 \fIInformation on Wine's internals\fR
 338 .IP \fBinfo\ class\fR
 339 Lists all Windows' class registered in Wine
 340 .IP \fBinfo\ class\ <id>\fR
 341 Prints information on Windows's class \fB<id>\fR
 342 .IP \fBinfo\ share\fR
 343 Lists all the dynamic libraries loaded in the debugged program
 344 (including .so files, NE and PE DLLs)
 345 .IP \fBinfo\ share\ N\fR
 346 Prints information on module at address \fBN\fR
 347 .IP \fBinfo\ regs\fR
 348 Prints the value of the CPU registers
 349 .IP \fBinfo\ all-regs\fR
 350 Prints the value of the CPU and Floating Point registers
 351 .IP \fBinfo\ segment\fR
 352 Lists all allocated segments (i386 only)
 353 .IP \fBinfo\ segment\ N\fR
 354 Prints information on segment \fBN\fR (i386 only)
 355 .IP \fBinfo\ stack\fR
 356 Prints the values on top of the stack
 357 .IP \fBinfo\ map\fR
 358 Lists all virtual mappings used by the debugged program
 359 .IP \fBinfo\ map\ N\fR
 360 Lists all virtual mappings used by the program of pid \fBN\fR
 361 .IP \fBinfo\ wnd\fR
 362 Displays the window hierarchy starting from the desktop window
 363 .IP \fBinfo\ wnd\ N\fR
 364 Prints information of Window of handle \fBN\fR
 365 .IP \fBinfo\ process\fR
 366 Lists all w-processes in Wine session
 367 .IP \fBinfo\ thread\fR
 368 Lists all w-threads in Wine session
 369 .IP \fBinfo\ exception\fR
 370 Lists the exception frames (starting from current stack frame)
 371 .PP
 372 Debug messages can be turned on and off as you are debugging using
 373 the \fBset\fR command, but only for channels initialized with the
 374 \fIWINEDEBUG\fR environment variable.
 375 .IP \fBset\ warn\ +\ win\fR
 376 Turns on warn on \fB'win'\fR channel
 377 .IP \fBset\ +\ win\fR
 378 Turns on warn/fixme/err/trace on \fB'win'\fR channel
 379 .IP \fBset\ -\ win\fR
 380 Turns off warn/fixme/err/trace on \fB'win'\fR channel
 381 .IP \fBset\ fixme\ -\ all\fR
 382 Turns off the 'fixme' class on all channels
 383 .PP
 384 .SS Gdb mode:
 385 .PP
 386 See the \fBgdb\fR documentation for all the \fBgdb\fR commands.
 387 .PP
 388 However, a few Wine's extension are available, through the
 389 \fBmonitor\fR command:
 390 .IP \fBmonitor\ wnd\fR
 391 Lists all window in the Wine session
 392 .IP \fBmonitor\ proc\fR
 393 Lists all processes in the Wine session
 394 .IP \fBmonitor\ mem\fR
 395 Displays memory mapping of debugged process
 396 .PP
 397 .SS Auto and minidump modes:
 398 .PP
 399 Since no user input is possible, no commands are available.
 400
 401 .SH ENVIRONMENT
 402 .IP \fBWINE_GDB\fR
 403 When used in \fBgdb\fR proxy mode, \fBWINE_GDB\fR specifies the name
 404 (and the path) of the executable to be used for \fBgdb\fR. \fB"gdb"\fR
 405 is used by default.
 406 .SH FILES
 407 No specific files are used (yet).
 408 .SH BUGS
 409 A lot.
 410 .SH AUTHORS
 411 The first version was written by Eric Youngdale.
 412 .PP
 413 See Wine developer's list for the rest of contributors.
 414 .SH "SEE ALSO"
 415 .BR winedbg "'s README file"
 416 .nf
 417 The Winelib User Guide
 418 .nf
 419 The Wine Developers Guide