Commit | Line | Data |
---|---|---|
12a74998 AJ |
1 | .\" -*- nroff -*- |
2 | .TH WINEDBG 1 "October 2005" "@PACKAGE_STRING@" "Wine Developers Manual" | |
deca2502 EP |
3 | .SH NAME |
4 | winedbg \- Wine's debugger | |
5 | .SH SYNOPSIS | |
81198f39 EP |
6 | .BR "winedbg " |
7 | .RI "[" " options " "] [" | |
8 | .BI "program name" | |
9 | .RI "[ program arguments ] |" | |
10 | .BI "pid" | |
11 | .RI "]" | |
12 | .PP | |
13 | .BR "winedbg " | |
deca2502 | 14 | .BI "--gdb" |
81198f39 | 15 | .RI "[" " options " "] [" |
deca2502 | 16 | .BI "program name" |
81198f39 | 17 | .RI "[ program arguments ] |" |
deca2502 EP |
18 | .BI "pid" |
19 | .RI "]" | |
81198f39 EP |
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" | |
deca2502 EP |
32 | .SH DESCRIPTION |
33 | .B winedbg | |
34 | is a debugger for Wine. It allows: | |
35 | .RS 4 | |
deca2502 | 36 | .nf |
82f810dc | 37 | + debugging native Win32 applications |
deca2502 | 38 | + debugging Winelib applications. |
deca2502 | 39 | + being a drop-in replacement for Dr Watson |
82f810dc | 40 | .fi |
deca2502 EP |
41 | .RE |
42 | .PP | |
43 | ||
44 | .SH MODES | |
81198f39 | 45 | \fBwinedbg\fR can be used in five modes. The first argument to the |
deca2502 EP |
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. | |
81198f39 EP |
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. | |
deca2502 | 54 | .IP \fB--auto\fR |
81198f39 | 55 | This mode is used when \fBwinedbg\fR is set up in \fIAeDebug\fR |
e7a49e7f | 56 | registry entry as the default debugger. \fBwinedbg\fR will then |
28dc5a8a | 57 | display basic information about a crash. This is useful for users |
deca2502 EP |
58 | who don't want to debug a crash, but rather gather relevant |
59 | information about the crash to be sent to developers. | |
81198f39 EP |
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. | |
deca2502 EP |
71 | |
72 | .SH OPTIONS | |
1c5d35fd EP |
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: | |
deca2502 | 86 | .PP |
81198f39 EP |
87 | .IP \fI--no-start\fR |
88 | \fBgdb\fR will not be automatically | |
deca2502 | 89 | started. Relevant information for starting \fBgdb\fR are printed on |
28dc5a8a | 90 | screen. This is somehow useful when not directly using \fBgdb\fR but |
deca2502 EP |
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 | |
1c5d35fd EP |
96 | In all modes, the rest of the command line, when passed, is used to |
97 | identify which programs, if any, has to debugged: | |
deca2502 EP |
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 | |
1c5d35fd | 104 | \fBwinedbg\fR will attach to the process which pid is \fBpid\fR (pids |
deca2502 EP |
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. | |
1c5d35fd | 107 | .IP \fBdefault\fR |
deca2502 EP |
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 | |
81198f39 | 112 | .SS Default mode, and while reloading a minidump file: |
deca2502 EP |
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 | |
803f3bd0 | 153 | Execute until return of current function is reached. |
deca2502 EP |
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 | |
81198f39 | 177 | .IP \fBbreak\ <id>\ N\fR |
deca2502 EP |
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. | |
95a3cd8e PS |
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. | |
deca2502 EP |
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 | |
81198f39 | 218 | .IP \fBframe\ N\fR |
deca2502 EP |
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: | |
deca2502 EP |
251 | .IP \fBlist\ 123,\ 234\fR |
252 | lists source lines from line 123 up to line 234 in current file | |
deca2502 | 253 | .IP \fBlist\ foo.c:1,56\fR |
82f810dc | 254 | lists source lines from line 1 up to 56 in file foo.c |
deca2502 EP |
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 | |
9c5e97aa | 302 | a UTF16 Unicode string |
deca2502 EP |
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 | |
81198f39 EP |
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 | |
deca2502 EP |
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 | |
09941267 JL |
354 | .IP \fBinfo\ all-regs\fR |
355 | Prints the value of the CPU and Floating Point registers | |
deca2502 EP |
356 | .IP \fBinfo\ segment\fR |
357 | Lists all allocated segments (i386 only) | |
81198f39 | 358 | .IP \fBinfo\ segment\ N\fR |
deca2502 EP |
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 | |
e7a49e7f | 367 | Displays the window hierarchy starting from the desktop window |
deca2502 EP |
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 | |
9261ef2d EP |
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. | |
deca2502 | 378 | .PP |
a35652d6 DS |
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. | |
26c427d5 | 382 | .IP \fBset\ warn\ +\ win\fR |
deca2502 EP |
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 | |
26c427d5 | 388 | .IP \fBset\ fixme\ -\ all\fR |
deca2502 EP |
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 | |
81198f39 | 399 | .IP \fBmonitor\ proc\fR |
deca2502 | 400 | Lists all processes in the Wine session |
81198f39 | 401 | .IP \fBmonitor\ mem\fR |
deca2502 EP |
402 | Displays memory mapping of debugged process |
403 | .PP | |
81198f39 | 404 | .SS Auto and minidump modes: |
deca2502 EP |
405 | .PP |
406 | Since no user input is possible, no commands are available. | |
407 | ||
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 |