| blob | fb91d6b50ac2186324b57f4d1f6854310a55f5e8 |
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 \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.
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