d3dx9: Handle ST_FXLC in d3dx9_parse_resource().
[wine] / programs / winedbg / winedbg.man.in
CommitLineData
12a74998
AJ
1.\" -*- nroff -*-
2.TH WINEDBG 1 "October 2005" "@PACKAGE_STRING@" "Wine Developers Manual"
deca2502
EP
3.SH NAME
4winedbg \- 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
34is 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
46program determines the mode winedbg will run in.
47.IP \fBdefault\fR
48Without any explicit mode, this is standard \fBwinedbg\fR operating
49mode. \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
52the front end for command handling, and \fBwinedbg\fR will proxy all
53debugging requests from \fBgdb\fR to the Win32 APIs.
deca2502 54.IP \fB--auto\fR
81198f39 55This mode is used when \fBwinedbg\fR is set up in \fIAeDebug\fR
e7a49e7f 56registry entry as the default debugger. \fBwinedbg\fR will then
28dc5a8a 57display basic information about a crash. This is useful for users
deca2502
EP
58who don't want to debug a crash, but rather gather relevant
59information about the crash to be sent to developers.
81198f39
EP
60.IP \fB--minidump\fR
61This mode is similar to the \fB--auto\fR one, except that instead of
62printing the information on the screen (as \fB--auto\fR does), it's
63saved into a minidump file. The name of the file is either passed on
64the command line, or generated by \fBWineDbg\fR when none is given.
65This file could later on be reloaded into \fBwinedbg\fR for further
66examination.
67.IP \fBfile.mdmp\fR
68This mode allows to reload into \fBwinedbg\fR the state of a debuggee
69which has been saved into a minidump file. See either the \fBminidump\fR
70command below, or the \fB--minidump mode\fR.
deca2502
EP
71
72.SH OPTIONS
1c5d35fd
EP
73When 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
77winedbg's command line, and then will exit. This can be handy for
78getting 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
82will exit.
83.PP
84
85When 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 89started. Relevant information for starting \fBgdb\fR are printed on
28dc5a8a 90screen. This is somehow useful when not directly using \fBgdb\fR but
deca2502
EP
91some graphical front-ends, like \fBddd\fR or \fBkgbd\fR.
92.IP \fI--with-xterm\fR
93This will run \fBgdb\fR in its own xterm instead of using the current
94Unix console for textual display.
95.PP
1c5d35fd
EP
96In all modes, the rest of the command line, when passed, is used to
97identify which programs, if any, has to debugged:
deca2502
EP
98.IP \fBprogram\ name\fR
99This is the name of an executable to start for a debugging
100session. \fBwinedbg\fR will actually create a process with this
101executable. If \fBprograms arguments\fR are also given, they will be
102used 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
105refer 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
108If nothing is specified, you will enter the debugger without any run
109nor 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
114Most 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
116details. See the \fIgdb\ differences\fR section later on to get a list
117of variations from \fBgdb\fR commands.
118.PP
119\fIMisc. commands\fR
120.IP \fBabort\fR
121Aborts the debugger.
122.IP \fBquit\fR
123Exits the debugger.
124.IP \fBattach\ N\fR
125Attach to a Wine-process (\fBN\fR is its ID, numeric or hexadecimal).
126IDs 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
130Detach from a Wine-process.
131.PP
132\fIHelp commands\fR
133.IP \fBhelp\fR
134Prints some help on the commands.
135.IP \fBhelp\ info\fR
136Prints some help on info commands
137.PP
138\fIFlow control commands\fR
139.IP \fBcont\fR
140Continue execution until next breakpoint or exception.
141.IP \fBpass\fR
142Pass the exception event up to the filter chain.
143.IP \fBstep\fR
144Continue execution until next C line of code (enters function call)
145.IP \fBnext\fR
146Continue execution until next C line of code (doesn't enter function
147call)
148.IP \fBstepi\fR
149Execute next assembly instruction (enters function call)
150.IP \fBnexti\fR
151Execute next assembly instruction (doesn't enter function call)
152.IP \fBfinish\fR
803f3bd0 153Execute until return of current function is reached.
deca2502
EP
154.PP
155\fBcont\fR, \fBstep\fR, \fBnext\fR, \fBstepi\fR, \fBnexti\fR can be
156postfixed by a number (N), meaning that the command must be executed N
157times before control is returned to the user.
158.PP
159\fIBreakpoints, watchpoints
160.IP \fBenable\ N\fR
161Enables (break|watch)-point #\fBN\fR
162.IP \fBdisable\fR
163Disables (break|watch)-point \fB#N\fR
164.IP \fBdelete\fR
165Deletes (break|watch)-point #\fBN\fR
166.IP \fBcond\ N\fR
167Removes any existing condition to (break|watch)-point \fBN\fR
168.IP \fBcond\ N\ <expr>\fR
169Adds 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
172breakpoint isn't triggered.
173.IP \fBbreak\ *\ N\fR
174Adds a breakpoint at address \fBN\fR
175.IP \fBbreak\ <id>\fR
176Adds a breakpoint at the address of symbol \fB<id>\fR
81198f39 177.IP \fBbreak\ <id>\ N\fR
deca2502
EP
178Adds a breakpoint at the line \fBN\fR inside symbol \fB<id>\fR.
179.IP \fBbreak\ N\fR
180Adds a breakpoint at line \fBN\fR of current source file.
181.IP \fBbreak\fR
182Adds a breakpoint at current \f$PC\fR address.
183.IP \fBwatch\ *\ N\fR
184Adds a watch command (on write) at address \fBN\fR (on 4 bytes).
185.IP \fBwatch\ <id>\fR
186Adds 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
189Adds a watch command (on read) at address \fBN\fR (on 4 bytes).
190.IP \fBrwatch\ <id>\fR
191Adds 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
194Lists all (break|watch)-points (with their state).
195.PP
196You can use the symbol \fBEntryPoint\fR to stand for the entry point of the Dll.
197.PP
198When setting a (break|watch)-point by \fB<id>\fR, if the symbol cannot
199be found (for example, the symbol is contained in a not yet loaded
200module), \fBwinedbg\fR will recall the name of the symbol and will try
201to set the breakpoint each time a new module is loaded (until it succeeds).
202.PP
203\fIStack manipulation\fR
204.IP \fBbt\fR
205Print calling stack of current thread.
206.IP \fBbt\ N\fR
207Print calling stack of thread of ID \fBN\fR. Note: this doesn't change
208the position of the current frame as manipulated by the \fBup\fR &
209\fBdn\fR commands).
210.IP \fBup\fR
211Goes up one frame in current thread's stack
212.IP \fBup\ N\fR
213Goes up \fBN\fR frames in current thread's stack
214.IP \fBdn\fR
215Goes down one frame in current thread's stack
216.IP \fBdn\ N\fR
217Goes down \fBN\fR frames in current thread's stack
81198f39 218.IP \fBframe\ N\fR
deca2502
EP
219Sets \fBN\fR as the current frame for current thread's stack.
220.IP \fBinfo\ locals\fR
221Prints information on local variables for current function frame.
222.PP
223\fIDirectory & source file manipulation\fR
224.IP \fBshow\ dir\fR
225Prints the list of dir:s where source files are looked for.
226.IP \fBdir\ <pathname>\fR
227Adds \fB<pathname>\fR to the list of dir:s where to look for source
228files
229.IP \fBdir\fR
230Deletes the list of dir:s where to look for source files
231.IP \fBsymbolfile\ <pathname>\fR
232Loads external symbol definition symbolfile \fB<pathname>\fR
233.IP \fBsymbolfile\ <pathname>\ N\fR
234Loads external symbol definition symbolfile \fB<pathname>\fR (applying
235an offset of \fBN\fR to addresses)
236.IP \fBlist\fR
237Lists 10 source lines forwards from current position.
238.IP \fBlist\ -\fR
239Lists 10 source lines backwards from current position
240.IP \fBlist\ N\fR
241Lists 10 source lines from line #\fBN\fR in current file
242.IP \fBlist\ <pathname>:N\fR
243Lists 10 source lines from line #\fBN\fR in file \fB<pathname>\fR
244.IP \fBlist\ <id>\fR
245Lists 10 source lines of function \fB<id>\fR
246.IP \fBlist\ *\ N\fR
247Lists 10 source lines from address \fBN\fR
248.PP
249You can specify the end target (to change the 10 lines value) using
250the ',' separator. For example:
deca2502
EP
251.IP \fBlist\ 123,\ 234\fR
252lists source lines from line 123 up to line 234 in current file
deca2502 253.IP \fBlist\ foo.c:1,56\fR
82f810dc 254lists source lines from line 1 up to 56 in file foo.c
deca2502
EP
255.PP
256\fIDisplaying\fR
257.PP
258A display is an expression that's evaluated and printed after the
259execution of any \fBwinedbg\fR's command.
260.IP \fBdisplay\fR
261.IP \fBinfo\ display\fR
262Lists the active displays
263.IP \fBdisplay\ <expr>\fR
264Adds a display for expression \f<expr>\fR
265.IP \fBdisplay\ /fmt\ <expr>\fR
266Adds a display for expression \fB<expr>\fR. Printing evaluated
267\fB<expr>\fR is done using the given format (see \fBprint\ command\fR
268for more on formats)
269.IP \fBdel\ display\ N\fR
270.IP \fBundisplay\ N\fR
271Deletes display #\fBN\fR
272.PP
273\fIDisassembly\fR
274.IP \fBdisas\fR
275Disassemble from current position
276.IP \fBdisas\ <expr>\fR
277Disassemble from address \fB<expr>\fR
278.IP \fBdisas\ <expr>,<expr>\fR
279Disassembles code between addresses specified by the two \fB<expr>\fR:s
280.PP
281\fIMemory\ (reading,\ writing,\ typing)\fR
282.IP \fBx\ <expr>\fR
283Examines memory at \fB<expr>\fR address
284.IP \fBx\ /fmt\ <expr>\fR
285Examines memory at \fB<expr>\fR address using format \fI/fmt\fR
286.IP \fBprint\ <expr>\fR
287Prints the value of \fB<expr>\fR (possibly using its type)
288.IP \fBprint\ /fmt\ <expr>\fR
289Prints the value of \fB<expr>\fR (possibly using its type)
290.IP \fBset\ <var>\ =\ <expr>\fR
291Writes the value of \fB<expr>\fR in \fB<var>\fR variable.
292.IP \fBwhatis\ <expr>\fR
293Prints the C type of expression \fB<expr>\fR
294.PP
295.IP \fI/fmt\fR
296is either \fI/<letter>\fR or \fI/<count><letter>\fR. \fI<letter>\fR
297can be:
298.RS 4
299.IP s
300an ASCII string
301.IP u
9c5e97aa 302a UTF16 Unicode string
deca2502
EP
303.IP i
304instructions (disassemble)
305.IP x
30632 bit unsigned hexadecimal integer
307.IP d
30832 bit signed decimal integer
309.IP w
31016 bit unsigned hexadecimal integer
311.IP c
312character (only printable 0x20-0x7f are actually printed)
313.IP b
3148 bit unsigned hexadecimal integer
315.IP g
316Win32 GUID
317.RE
318.PP
319\fIExpressions\fR
320.PP
321Expressions in Wine Debugger are mostly written in a C form. However,
322there are a few discrepancies:
323.PP
324.RS 4
325Identifiers can take a '!' in their names. This allows mainly to
326specify a module where to look the module from: \fIUSER32!CreateWindowExA\fR.
327.PP
328In cast operation, when specifying a structure or an union, you must
329use the struct or union key word (even if your program uses a typedef).
330.RE
331.PP
332When specifying an identifier \fB<id>\fR, if several symbols with
333this name exist, the debugger will prompt for the symbol you want to
334use. Pick up the one you want from its number.
335.PP
81198f39
EP
336\fIMisc.\fR
337.PP
338.IP \fBminidump\ file.mdmp\fR
339saves the debugging context of the debuggee into a minidump file called
340file.mdmp
341.PP
deca2502
EP
342\fIInformation on Wine's internals\fR
343.IP \fBinfo\ class\fR
344Lists all Windows' class registered in Wine
345.IP \fBinfo\ class\ <id>\fR
346Prints information on Windows's class \fB<id>\fR
347.IP \fBinfo\ share\fR
348Lists all the dynamic libraries loaded in the debugged program
349(including .so files, NE and PE DLLs)
350.IP \fBinfo\ share\ N\fR
351Prints information on module at address \fBN\fR
352.IP \fBinfo\ regs\fR
353Prints the value of the CPU registers
09941267
JL
354.IP \fBinfo\ all-regs\fR
355Prints the value of the CPU and Floating Point registers
deca2502
EP
356.IP \fBinfo\ segment\fR
357Lists all allocated segments (i386 only)
81198f39 358.IP \fBinfo\ segment\ N\fR
deca2502
EP
359Prints information on segment \fBN\fR (i386 only)
360.IP \fBinfo\ stack\fR
361Prints the values on top of the stack
362.IP \fBinfo\ map\fR
363Lists all virtual mappings used by the debugged program
364.IP \fBinfo\ map\ N\fR
365Lists all virtual mappings used by the program of pid \fBN\fR
366.IP \fBinfo\ wnd\fR
e7a49e7f 367Displays the window hierarchy starting from the desktop window
deca2502
EP
368.IP \fBinfo\ wnd\ N\fR
369Prints information of Window of handle \fBN\fR
370.IP \fBinfo\ process\fR
371Lists all w-processes in Wine session
372.IP \fBinfo\ thread\fR
373Lists all w-threads in Wine session
9261ef2d
EP
374.IP \fBinfo\ frame\fR
375Lists the exception frames (starting from current stack frame). You
376can also pass, as optional argument, a thread id (instead of current
377thread) to examine its exception frames.
deca2502 378.PP
a35652d6
DS
379Debug messages can be turned on and off as you are debugging using
380the \fBset\fR command, but only for channels initialized with the
381\fIWINEDEBUG\fR environment variable.
26c427d5 382.IP \fBset\ warn\ +\ win\fR
deca2502
EP
383Turns on warn on \fB'win'\fR channel
384.IP \fBset\ +\ win\fR
385Turns on warn/fixme/err/trace on \fB'win'\fR channel
386.IP \fBset\ -\ win\fR
387Turns off warn/fixme/err/trace on \fB'win'\fR channel
26c427d5 388.IP \fBset\ fixme\ -\ all\fR
deca2502
EP
389Turns off the 'fixme' class on all channels
390.PP
391.SS Gdb mode:
392.PP
393See the \fBgdb\fR documentation for all the \fBgdb\fR commands.
394.PP
395However, a few Wine's extension are available, through the
396\fBmonitor\fR command:
397.IP \fBmonitor\ wnd\fR
398Lists all window in the Wine session
81198f39 399.IP \fBmonitor\ proc\fR
deca2502 400Lists all processes in the Wine session
81198f39 401.IP \fBmonitor\ mem\fR
deca2502
EP
402Displays memory mapping of debugged process
403.PP
81198f39 404.SS Auto and minidump modes:
deca2502
EP
405.PP
406Since no user input is possible, no commands are available.
407
408.SH ENVIRONMENT
409.IP \fBWINE_GDB\fR
410When 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
412is used by default.
413.SH FILES
414No specific files are used (yet).
415.SH BUGS
416A lot.
417.SH AUTHORS
418The first version was written by Eric Youngdale.
419.PP
420See Wine developer's list for the rest of contributors.
421.SH "SEE ALSO"
422.BR winedbg "'s README file"
423.nf
424The Winelib User Guide
425.nf
426The Wine Developers Guide