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