| blob | 1155111dfac2a8a8e601453d2d9861b4059bd57d |
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
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.
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
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.
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 \fBrwatch\ *\ N\fR
189 Adds a watch command (on read) at address \fBN\fR (on 4 bytes).
190 .IP \fBrwatch\ <id>\fR
191 Adds a watch command (on read) at the address of symbol
192 \fB<id>\fR. Size depends on size of \fB<id>\fR.
193 .IP \fBinfo\ break\fR
194 Lists all (break|watch)-points (with their state).
195 .PP
196 You can use the symbol \fBEntryPoint\fR to stand for the entry point of the Dll.
197 .PP
198 When setting a (break|watch)-point by \fB<id>\fR, if the symbol cannot
199 be found (for example, the symbol is contained in a not yet loaded
200 module), \fBwinedbg\fR will recall the name of the symbol and will try
201 to set the breakpoint each time a new module is loaded (until it succeeds).
202 .PP
203 \fIStack manipulation\fR
204 .IP \fBbt\fR
205 Print calling stack of current thread.
206 .IP \fBbt\ N\fR
207 Print calling stack of thread of ID \fBN\fR. Note: this doesn't change
208 the position of the current frame as manipulated by the \fBup\fR &
209 \fBdn\fR commands).
210 .IP \fBup\fR
211 Goes up one frame in current thread's stack
212 .IP \fBup\ N\fR
213 Goes up \fBN\fR frames in current thread's stack
214 .IP \fBdn\fR
215 Goes down one frame in current thread's stack
216 .IP \fBdn\ N\fR
217 Goes down \fBN\fR frames in current thread's stack
218 .IP \fBframe\ N\fR
219 Sets \fBN\fR as the current frame for current thread's stack.
220 .IP \fBinfo\ locals\fR
221 Prints information on local variables for current function frame.
222 .PP
223 \fIDirectory & source file manipulation\fR
224 .IP \fBshow\ dir\fR
225 Prints the list of dir:s where source files are looked for.
226 .IP \fBdir\ <pathname>\fR
227 Adds \fB<pathname>\fR to the list of dir:s where to look for source
228 files
229 .IP \fBdir\fR
230 Deletes the list of dir:s where to look for source files
231 .IP \fBsymbolfile\ <pathname>\fR
232 Loads external symbol definition symbolfile \fB<pathname>\fR
233 .IP \fBsymbolfile\ <pathname>\ N\fR
234 Loads external symbol definition symbolfile \fB<pathname>\fR (applying
235 an offset of \fBN\fR to addresses)
236 .IP \fBlist\fR
237 Lists 10 source lines forwards from current position.
238 .IP \fBlist\ -\fR
239 Lists 10 source lines backwards from current position
240 .IP \fBlist\ N\fR
241 Lists 10 source lines from line #\fBN\fR in current file
242 .IP \fBlist\ <pathname>:N\fR
243 Lists 10 source lines from line #\fBN\fR in file \fB<pathname>\fR
244 .IP \fBlist\ <id>\fR
245 Lists 10 source lines of function \fB<id>\fR
246 .IP \fBlist\ *\ N\fR
247 Lists 10 source lines from address \fBN\fR
248 .PP
249 You can specify the end target (to change the 10 lines value) using
250 the ',' separator. For example:
251 .IP \fBlist\ 123,\ 234\fR
252 lists source lines from line 123 up to line 234 in current file
253 .IP \fBlist\ foo.c:1,56\fR
254 lists source lines from line 1 up to 56 in file foo.c
255 .PP
256 \fIDisplaying\fR
257 .PP
258 A display is an expression that's evaluated and printed after the
259 execution of any \fBwinedbg\fR's command.
260 .IP \fBdisplay\fR
261 .IP \fBinfo\ display\fR
262 Lists the active displays
263 .IP \fBdisplay\ <expr>\fR
264 Adds a display for expression \f<expr>\fR
265 .IP \fBdisplay\ /fmt\ <expr>\fR
266 Adds a display for expression \fB<expr>\fR. Printing evaluated
267 \fB<expr>\fR is done using the given format (see \fBprint\ command\fR
268 for more on formats)
269 .IP \fBdel\ display\ N\fR
270 .IP \fBundisplay\ N\fR
271 Deletes display #\fBN\fR
272 .PP
273 \fIDisassembly\fR
274 .IP \fBdisas\fR
275 Disassemble from current position
276 .IP \fBdisas\ <expr>\fR
277 Disassemble from address \fB<expr>\fR
278 .IP \fBdisas\ <expr>,<expr>\fR
279 Disassembles code between addresses specified by the two \fB<expr>\fR:s
280 .PP
281 \fIMemory\ (reading,\ writing,\ typing)\fR
282 .IP \fBx\ <expr>\fR
283 Examines memory at \fB<expr>\fR address
284 .IP \fBx\ /fmt\ <expr>\fR
285 Examines memory at \fB<expr>\fR address using format \fI/fmt\fR
286 .IP \fBprint\ <expr>\fR
287 Prints the value of \fB<expr>\fR (possibly using its type)
288 .IP \fBprint\ /fmt\ <expr>\fR
289 Prints the value of \fB<expr>\fR (possibly using its type)
290 .IP \fBset\ <var>\ =\ <expr>\fR
291 Writes the value of \fB<expr>\fR in \fB<var>\fR variable.
292 .IP \fBwhatis\ <expr>\fR
293 Prints the C type of expression \fB<expr>\fR
294 .PP
295 .IP \fI/fmt\fR
296 is either \fI/<letter>\fR or \fI/<count><letter>\fR. \fI<letter>\fR
297 can be:
298 .RS 4
299 .IP s
300 an ASCII string
301 .IP u
302 a UTF16 Unicode string
303 .IP i
304 instructions (disassemble)
305 .IP x
306 32 bit unsigned hexadecimal integer
307 .IP d
308 32 bit signed decimal integer
309 .IP w
310 16 bit unsigned hexadecimal integer
311 .IP c
312 character (only printable 0x20-0x7f are actually printed)
313 .IP b
314 8 bit unsigned hexadecimal integer
315 .IP g
316 Win32 GUID
317 .RE
318 .PP
319 \fIExpressions\fR
320 .PP
321 Expressions in Wine Debugger are mostly written in a C form. However,
322 there are a few discrepancies:
323 .PP
324 .RS 4
325 Identifiers can take a '!' in their names. This allows mainly to
326 specify a module where to look the module from: \fIUSER32!CreateWindowExA\fR.
327 .PP
328 In cast operation, when specifying a structure or an union, you must
329 use the struct or union key word (even if your program uses a typedef).
330 .RE
331 .PP
332 When specifying an identifier \fB<id>\fR, if several symbols with
333 this name exist, the debugger will prompt for the symbol you want to
334 use. Pick up the one you want from its number.
335 .PP
336 \fIMisc.\fR
337 .PP
338 .IP \fBminidump\ file.mdmp\fR
339 saves the debugging context of the debuggee into a minidump file called
340 file.mdmp
341 .PP
342 \fIInformation on Wine's internals\fR
343 .IP \fBinfo\ class\fR
344 Lists all Windows' class registered in Wine
345 .IP \fBinfo\ class\ <id>\fR
346 Prints information on Windows's class \fB<id>\fR
347 .IP \fBinfo\ share\fR
348 Lists all the dynamic libraries loaded in the debugged program
349 (including .so files, NE and PE DLLs)
350 .IP \fBinfo\ share\ N\fR
351 Prints information on module at address \fBN\fR
352 .IP \fBinfo\ regs\fR
353 Prints the value of the CPU registers
354 .IP \fBinfo\ all-regs\fR
355 Prints the value of the CPU and Floating Point registers
356 .IP \fBinfo\ segment\fR
357 Lists all allocated segments (i386 only)
358 .IP \fBinfo\ segment\ N\fR
359 Prints information on segment \fBN\fR (i386 only)
360 .IP \fBinfo\ stack\fR
361 Prints the values on top of the stack
362 .IP \fBinfo\ map\fR
363 Lists all virtual mappings used by the debugged program
364 .IP \fBinfo\ map\ N\fR
365 Lists all virtual mappings used by the program of pid \fBN\fR
366 .IP \fBinfo\ wnd\fR
367 Displays the window hierarchy starting from the desktop window
368 .IP \fBinfo\ wnd\ N\fR
369 Prints information of Window of handle \fBN\fR
370 .IP \fBinfo\ process\fR
371 Lists all w-processes in Wine session
372 .IP \fBinfo\ thread\fR
373 Lists all w-threads in Wine session
374 .IP \fBinfo\ frame\fR
375 Lists the exception frames (starting from current stack frame). You
376 can also pass, as optional argument, a thread id (instead of current
377 thread) to examine its exception frames.
378 .PP
379 Debug messages can be turned on and off as you are debugging using
380 the \fBset\fR command, but only for channels initialized with the
381 \fIWINEDEBUG\fR environment variable.
382 .IP \fBset\ warn\ +\ win\fR
383 Turns on warn on \fB'win'\fR channel
384 .IP \fBset\ +\ win\fR
385 Turns on warn/fixme/err/trace on \fB'win'\fR channel
386 .IP \fBset\ -\ win\fR
387 Turns off warn/fixme/err/trace on \fB'win'\fR channel
388 .IP \fBset\ fixme\ -\ all\fR
389 Turns off the 'fixme' class on all channels
390 .PP
391 .SS Gdb mode:
392 .PP
393 See the \fBgdb\fR documentation for all the \fBgdb\fR commands.
394 .PP
395 However, a few Wine's extension are available, through the
396 \fBmonitor\fR command:
397 .IP \fBmonitor\ wnd\fR
398 Lists all window in the Wine session
399 .IP \fBmonitor\ proc\fR
400 Lists all processes in the Wine session
401 .IP \fBmonitor\ mem\fR
402 Displays memory mapping of debugged process
403 .PP
404 .SS Auto and minidump modes:
405 .PP
406 Since no user input is possible, no commands are available.
408 .SH ENVIRONMENT
409 .IP \fBWINE_GDB\fR
410 When used in \fBgdb\fR proxy mode, \fBWINE_GDB\fR specifies the name
411 (and the path) of the executable to be used for \fBgdb\fR. \fB"gdb"\fR
412 is used by default.
413 .SH FILES
414 No specific files are used (yet).
415 .SH BUGS
416 A lot.
417 .SH AUTHORS
418 The first version was written by Eric Youngdale.
419 .PP
420 See Wine developer's list for the rest of contributors.
421 .SH "SEE ALSO"
422 .BR winedbg "'s README file"
423 .nf
424 The Winelib User Guide
425 .nf
426 The Wine Developers Guide